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Preface 


This book contains information about writing LDAP dient applications, including: 

• Various sample LDAP dient programs 

• And LDAP dient library that is used to provide application access to the LDAP 
Servers 


Who should read this book 

This book is intended for programmers. 


Publications 

Read the descriptions of the IBM® Tivoli" Directory Server library to determine 
which publications you might find helpful. After you determine the publications 
you need, refer to the instructions for accessing publications online. 


IBM Tivoli Directory Server library 

The publications in the IBM Tivoli Directory Server library are: 

IBM Tivoli Directo ry Server Version 5.2 Read me Addendum 

Go to the Tivoli Software Library Web site to access the Readme 
Addendum for IBM Tivoli Directory Server 5.2, which cont ains importa nt 


information that was not include d in the Readme files. See |" Accessing 


publications online" on page viii| for information about accessing online 
publications. 

IBM Tivoli Directory Server Version 5.2 Client Readme 

Contains last-minute information about the dient. 

IBM Tivoli Directory Server Version 5.2 Server Readme 

Contains last-minute information about the Server. 


IBM Tivoli Directory Server Version 5.2 Web Administration Tool Readme 

Contains last-minute information about the Web Administration Tool. This 
Readme is available from the main panel of the Web Administration Tool. 

IBM Tivoli Directory Server Version 5.2 Installation and Configuration Guide 

Contains complete information for installing the IBM Tivoli Directory 
Server dient, Server, and Web Administration Tool. Includes information 
about migrating from a previous version of IBM Tivoli Directory Server or 
SecureWay® Directory. 

IBM Tivoli Directory Server Version 5.2 Tuning Guide 

Contains information about tuning your Server for better performance. 

IBM Tivoli Directory Server Version 5.2 Administration Guide 

Contains instructions for performing administrator tasks through the Web 
Administration Tool or the command line. 

IBM Tivoli Directory Server Version 5.2 Plug-in Reference 

Contains information about writing Server plug-ins. 
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Related publications 


Information related to the IBM Tivoli Directory Server is available in the following 
publications: 


• The IBM Tivoli Directory Server Version 5.2 uses the JNDI dient from Sun 
Microsystems. For information about the JNDI dient, refer to the Java™ Naming 
and Directory Interface™ 1.2.1 Syecification on the Sun Microsys tems Web site at 
http://java.sun.com/products/jndi/1.2/javadoc/index.html . 


• The Tivoli Software Library provides a variety of Tivoli publications such as 
white papers, datasheets, demonstrations, redbooks, and announcement letters. 
The Tivoli Software Library is available on the W eb at: 
http: / / www. ibm. com / Software / tivoli / library / 


The Tivoli Software Glossary includes definitions for many of the technical terms 
related to Tivoli Software. The Tivoli Software Glossary is available, in English 
only, from the Glossary link on the left side of the Tiv oli Software Library Web 


page http://www.ibm.com/software/tivoli/library/ 


Accessing publications online 


The publications for this product are available online in Portable Document Format 
(PDF) or Hypert ext Markup Language (HTML) format, or both in the Tivoli 
Software library: http://www.ibm.com/software/tivoli/library 


To locate product publications in the library, dick the Product manuals link on the 
left side of the Library page. Then, locate and dick the name of the product on the 
Tivoli Software information center page. 


Information is organized by product and includes READMEs, installation guides, 
user's guides, administrator's guides, and developer's references. 


Note: To ensure proper printing of PDF publications, select the Fit to page check 
box in the Adobe Acrobat Print window (which is available when you dick 

File ■* Print). 


Accessibility 

Accessibility features help a user who has a physical disability, such as restricted 
mobility or limited vision, to use Software products successfully. With this product, 
you can use assistive technologies to hear and navigate the interface. After 
installation you also can use the keyboard instead of the mouse to operate all 
features of the graphical user interface. 


Contacting Software Support 

Betöre contacting IBM Tivoli Software support with a problem, refer to IBM System 
Management and Tivoli Software Web site at: 


http://www.ibm.com/software/sysmgmt/products/support/ 


If you need additional help, contact Software support by using the methods 
described in the IBM Software Support Guide at the following Web site: 


http://techsupport.services.ibm.com/guides/handbook.html 


The guide provides the following information: 

• Registration and eligibility requirements for receiving support 
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• Telephone numbers and e-mail addresses, depending on the country in which 
you are located 

• A list of information you should gather before contacting customer support 


Conventions used in this book 

This reference uses several conventions for special terms and actions and for 

operating system-dependent commands and paths. 

Typeface conventions 

The following typeface conventions are used in this reference: 

Bold Lowercase commands or mixed case commands that are difficult to 

distinguish from surrounding text, keywords, parameters, options, names 
of Java classes, and objects are in bold. 

Italic Titles of publications, and special words or phrases that are emphasized 
are in italic. 


<Italic> 

Variables are set off with < > and are in <italic>. 

Monospace 

Code examples, command lines, screen output, file and directory names 
that are difficult to distinguish from surrounding text, System messages, 
text that the user must type, and values for arguments or command 
options are in monospace. 

Operating System differences 

This book uses the UNIX® convention for specifying environment variables and for 
directory notation. When using the Windows® command line, replace $variable 
with %variable% for environment variables and replace each forward slash (/) with 
a backslash (\) in directory paths. If you are using the bash shell on a Windows 
System, you can use the UNIX conventions. 
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Chapter 1. IBM Directory C-Client SDK overview 

The Lightweight Directory Access Protocol (LDAP) provides TCP/IP access to 
LDAP-compliant Servers. The IBM Directory Server C-Client SDK includes various 
sample LDAP dient programs, and an LDAP dient library used to provide 
application access to the LDAP Servers. 


See the following sections for more information: 


"LDAP version support 

/ 

"LDAP API overview" 


"Updates for IBM Directory Server C-Client Version 5.2" on page 3 


LDAP Version support 


The IBM Directory Server C-Client SDK provides support for both LDAP Version 2 
and LDAP Version 3 application programming inter faces (APIs) and protocols. The 


LDAP SDK APIs are based upon the Internet Draft, |"C LDAP Application Program 


Interface ", which is classified as a work in progress. 


The LDAP API provides typical directory functions such as read, write and search. 
With the advent of support for LDAP Version 3 APIs and protocols, the following 
features are also supported: 

• LDAP V3 referrals and search references. 

• Improved internationalization with UTF-8 support for Distinguished Names 
(DNs) and strings that are passed into, and returned from, the LDAP APIs. 
Support for converting string data between the local code page and UTF-8 is 
also provided. When running as an LDAP V2 application, DNs and strings 
remain limited to the IA5 character set. 


As provided by the IBM Directory server's dynamic Schema capability, an LDAP 
application can add, modify and change eleme nts of the Schema (see 


Appendix B, "LDAP V3 Schema", on page 175 for more information). 


Controls for the LDAP Server and dient. 


With the C-Client SDK, an application that uses the ldap_open API defaults to the 
LDAP V2 protocol. Existing LDAP applications continue to work and can 
interoperate with both LDAP V2 Servers and LDAP V3 Servers. 

An application that uses the ldap_init API defaults to the LDAP V3 protocol with 
optional bind. An LDAP V3 application does not necessarily interoperate with an 
LDAP Server that supports only LDAP V2 protocols. 

Note: An application can use the ldap_set_option API to change its LDAP protocol 
Version. This is done after using ldap_open or ldap_init but betöre issuing a 
bind or any other Operation that results in contacting the Server. 


LDAP API overview 

The set of LDAP APIs is designed to provide a suite of functions that can be used 
to develop directory-enabled applications. Directory-enabled applications typically 
connect to one or more directories and perform various directory-related 
operations, such as: 
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• Adding entries 

• Searching the directories and obtaining the resulting list of entries 

• Deleting entries 

• Modifying entries 

• Renaming entries 

The type of information that is managed in the directory depends on the nature of 
the application. Directories often are used to provide public access to information 
about people. For example: 

• phone numbers 

• e-mail addresses 

• fax numbers 

• mailing addresses 

Increasingly, directories are being used to manage and publish other types of 
information. For example: 

• Configuration information 

• Public key certificates (managed by certification authorities (CAs)) 

• Access control information 

• Locating information (how to find a Service) 

The LDAP API provides for both synchronous and asynchronous access to a 
directory. Asynchronous access enables your application to do other work while 
waiting for the results of a directory Operation to be returned by the Server. 

Source code, example makefile, and executable programs are provided for 
performing the following operations: 

• ldapsearch (searches the directory) 

• ldapmodify (modifies information in the directory) 

• ldapdelete (deletes information from the directory) 

• ldapmodrdn (modifies the Relative Distinguished Name (RDN) of an entry in 
the directory) 

Typical API usage 

The basic interaction is as follows: 

1. A connection is made to an LDAP Server by calling either ldap_init or 
ldap_ssl_init, which is used to establish a secure connection over Secure Sockets 
Layer (SSL). 

2. An LDAP bind Operation is performed by calling ldap_simple_bind. The bind 
Operation is used to authenticate to the directory Server. Note that the LDAP V3 
API and protocol permits the bind to be skipped, in which case the access 
rights associated with anonymous access are obtained. 

3. Other operations are performed by calling one of the synchronous or 
asynchronous routines (for example, ldap_search_s or ldap_search followed by 
ldap_result). 

4. Results returned from these routines are interpreted by calling the LDAP 
parsing routines, which include operations such as: 

• ldap_first_entry, ldap_next_entry 

• ldap_get_dn 

• ldap_first_attribute, ldap_next_attribute 
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• ldap_get_values 

• ldap_parse_result (new for LDAP V3) 

5. The LDAP connection is terminated by calling ldap_unbind. 

When handling a dient referral to another Server, the ldap_set_rebind_proc routine 
defines the entry point of a routine called when an LDAP bind Operation is 
needed. 

Displaying results 

Results obtained from the LDAP search routines can be accessed by calling: 

• ldap_first_entry and ldap_next_entry to step through the entries returned 

• ldap_first_attribute and ldap_next_attribute to step through an entry's attributes 

• ldap_get_values to retrieve a given attribute's value 

• printf or some other display or usage method 

Uniform Resource Locators (URLs) 

Use the ldap_url routines to test a URL to see if it is an LDAP URL, to parse 
LDAP URLs into their component pieces, and to initiate searches directly using an 
LDAP URL. Some examples of these routines are ldap_url_parse, 
ldap_url_search_s, and ldap_is_ldap_url. 

Secure Socket Layer (SSL) support 

The LDAP API has been extended to support connections that are protected by the 
SSL protocol. This can be used to provide strong authentication between the dient 
and Server, as well as data encryption of LDAP messages that flow between the 
dient and the LDAP Server. The ldap_ssl_client_init() and ldap_ssl_init() APIs are 
provided to initialize the SSL function, and to create a secure SSL connection. 


Updates for IBM Directory Server C-Client Version 5.2 

The following are enhancements available with the IBM Tivoli Directory Server 
C-Client Version 5.2. 

New dient Utilities 

Three new dient Utilities have been added: 

ldaptrace 

The administration tracing utility, ldaptrace, is used to dynamically activate 
or deactivate tracing of the Directory Server. This extended Operation can 
also be used to set the message level and specify the name of the file to the 
output is written. 

New APIs 

The following new APIs are provided: 


"LDAP_CREATE_PROXYAUTH_CONTROL" on page 54 

"LDAP START TLS" on page 131 



"LDAP STOP TLS" on page 139 


"LDAP_GET_BIND_CONTROLS" on page 74 
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Kerberos 1.3 

For IBM Directory Server Version 5.1, Kerberos 1.3 is used on the AIX® operating 
Systems. For IBM Tivoli Directory Server Version 5.2, Kerberos 1.1 is used on the 
Windows NT® and Windows 2000 operating Systems. IBM Tivoli Directory Server 
Version 5.2 does not support Kerberos authentication on the Solaris or HP 
operating Systems. 

Idap.conf renamed ibmldap.conf 

In IBM Tivoli Directory Server Version 5.2, the Idap.conf file has been renamed 
ibmldap.conf 
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Chapter 2. LDAP Utilities 


This chapter provides detailed information about the following dient Utilities: 


"LDAPMODIFY, LDAPADD" 


"LDAPCHANGEPWD" on page 11 

"LDAPDELETE" on page 14 


"LDAPEXOP" on page 18 



"LDAPMODRDN" on page 2 

3 

"LDAPSEARCH" on page 27 


"IBMDIRCTL" on page 35 




Note: -D binddn -w passwd does not call bind functions on administrator DNs for 
these Utilities. 


LDAPMODIFY, LDAPADD 

LDAP modify-entry and LDAP add-entry tools 

Synopsis 

ldapmodify [-a] [-b] [-c] [-C charset] [-d debuglevel][-D binddn] [-g] [-G realm] [-i file] 
[-h ldaphost] [-k] [-K keyfile] [-m mechanism] [-M] [-N certificatename] 

[-0 maxhops] [-p ldapport] [-P keyfilepw] [-r] [-R] [-U username] [-v] [-V] 

[-w passwd | ?] [-y proxydn] [-Y] [-Z] 


ldapadd [-a] [-b] [-c] [-C charset] [-d debuglevel] [-D binddn] [-g] [-i file] 
[-h ldaphost] [-k] [-K keyfile] [-m mechanism] [-M] [-N certi fi catename] 

[-0 maxhops] [-p ldapport] [-P keyfilepw] [-r] [-R] [-Ü username] [-v] [-V] 
[-w passwd | ?] [-y proxydn] [-Y] [-Z] 


Description 

ldapmodify is a command-line interface to the ldap_modify and ldap_add library 
calls. Invoking ldapadd is equivalent to invoking ldapmodify with the -a (add 
new entry) flag turned on. 

ldapmodify opens a connection to an LDAP Server and binds to the Server. You 
can use ldapmodify to modify or add entries. The entry information is read from 
Standard input or from file through the use of the -i Option. 

To display syntax help for ldapmodify or ldapadd, type 
ldapmodify -? 

or 

ldapadd -? 

Options 

-a Add new entries. The default action for ldapmodify is to modify existing 
entries. If invoked as ldapadd, this flag is always set. 
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-b Assume that any values that start with a forward slash ( / ) are binary 

values and that the actual value is in a file whose path is specified in place 
of the value. 


-c Continuous Operation mode. Errors are reported, but ldapmodify 

continues with modifications. Otherwise the default action is to exit after 
reporting an error. 


-C charset 

Specifies that strings supplied as input to the ldapmodify and ldapadd 
Utilities are represented in a local character set as specified by charset, and 
must be converted to UTF-8. When the ldapmodify and ldapadd records 
are received from Standard input, the specified charset value is used to 
convert the attribute values that are designated as strings; that is, the 
attribute types are followed by a single colon. If the records are received 
from an LDIF file that contains a charset tag, the charset tag in th e LDIF 


file overrides the charset value specified on the com mand-line. See 


'IANA 


character sets supported by platform" on page 184| for the specific charset 


values that are supported for each operating System platform. 


Note: The supported values for charset are the same values supported for 
the charset tag that is optionally defined in Version 1 LDIF files. 

-d debuglevel 

Set the LDAP debugging level to debuglevel. 


-D binddn 

Use bind dn to bind to the LDAP directory. binddn is a string-repre sented 
DN (see Appendix C, "LDAP distinguished names", on page 1791. 


-G realm 

Specify the name of the realm. When used with the -m DIGEST-MD5, the 
value is passed to the Server during the bind. 


-h Idaphost 

Specify an altemate host on which the LDAP Server is running. 


-i file Read the entry modification information from an LDIF file instead of from 
Standard input. If an LDIF file is not specified, you must use Standard 
input to specify the update records in LDIF format. 


Note: This Option has changed from the 4.1 release. Formerly, -f was used 
to specify a file. 

-k Specifies to use Server administration control. 

-K keyfile 

Specify the name of the SSL key database file with default extension of 
kdb. If the key database file is not in the current directory, specify the 
fully-qualified key database filename. If a key database filename is not 
specified, this utility first looks for the presence of the SSLjCEYRING 
environment variable with an associated filename. If the SSLjCEYRING 
environment variable is not defined, the default keyring file is used, if 
present. 

A default keyring file (ldapkey.kdb), and the associated password stashfile 
(ldapkey.sth), are installed in the /lib directory under LDAPHOME, where 
LDAPHOME is the path to the installed LDAP support. LDAPHOME 
varies by operating System platform: 
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Windows 

c:\Program Files\IBM\LDAP 
AIX /usr/ldap 
Solaris 

/opt/IBMldapc 
Linux /usr/ldap 
HP-UX 

/usr/IBMldap 


Note: This is the default installation location. The actual 
determined during installatio n. 


Default keyring and password 


See 

database files and default CAs. 


for more information 


LDAPHOME 
about default 


is 

key 


If a keyring database file cannot be located, a hard-coded set of default 
trusted certificate authority roots is used. The key database file typically 
contains one or more certificates of CAs that are trusted by the dient. 
These types of X.509 certificates are also known as trusted roots. For m ore 


information on managin g an SSL key database, see|Chapter 4, "Using 


gsk7IKM", on page 149| A lso see the pSSL notes" on page 10| and 


/ LDAP_SSL" on page 131 for more information about SSL and certificates. 


This parameter effectively enables the -Z switch, 
m mechanism 

Use mechanism to specify the Simple Authentication Security Layer (SASL) 
mechanism to be used to bind to the Server. The ldap_sasl_bind_s() API is 
used. The -m parameter is ignored if -V 2 is set. If -m is not specified, 
simple authentication is used. 

M Manage referral objects as regulär entries. 

N certificatename 

Specify the label associated with the dient certificate in the key database 
file. If the LDAP Server is configured to perform Server authentication only, 
a dient certificate is not required. If the LDAP Server is configured to 
perform dient and Server Authentication, a dient certificate might be 
required. certificatename is not required if a default certificate/private key 
pair has been designated as the default. Similarly, certificatename is not 
required if there is a single certificate/private key pair in the designated 
key database file. This parameter is ignored if neither -Z nor -K is 
specified. 

O maxhops 

Specify maxhops to set the maximum number of hops that the dient 
library takes when chasing referrals. The default number is 10. 

p Idapport 

Specify an altemate TCP port where the ldap Server is listening. The 
default LDAP port is 389. If -p is not specified and -Z is specified, the 
default LDAP SSL port 636 is used. 

P keyfilepw 

Specify the key database password. This password is required to access the 
encrypted information in the key database file, which might include one or 
more private keys. If a password stash file is associated with the key 
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database file, the password is obtained from the password stash file, and 
the -P parameter is not required. This parameter is ignored if neither -Z 
nor -K is specified. 

-r Replace existing values by default. 

-R Specifies that referrals are not to be automatically followed. 

-U username 

Specifies the username. This is required with -m DIGEST-MD5 and ignored 
when any other mechanism is used. The value username depends on what 
attribute the Server is configured to use. It might be a uid or any other 
value that is used to locate the entry. 

-v Use verbose mode, with many diagnostics written to Standard output. 

-V Specifies the LDAP version to be used by ldapmodify when it binds to the 

LDAP Server. By default, an LDAP V3 connection is established. To 
explicitly select LDAP V3, specify -V 3. Specify -V 2 to run as an LDAP V2 
application. An application, like ldapmodify, selects LDAP V3 as the 
preferred protocol by using ldap_init instead of ldap_open. 

-w passzvd I ? 

Use passzvd as the password for authentication. Use the ? to generate a 
password prompt. Using this prompt prevents your password from being 
visible through the ps command. 

-Z Use a secure SSL connection to communicate with the LDAP Server. The -Z 
Option is only supported when the SSL componentry, as provided by the 
GSKit, is installed. 

Input format 

The contents of file (or Standard input if no -i flag is given on the command line) 
must conform to the LDIF format. 

Alternative input format 

An alternative input format is supported for compatibility with older versions of 
ldapmodify. This format consists of one or more entries separated by blank lines, 
where each entry looks like the following: 

Distinguished Marne (DN) 

attr=val iie 

[attr=value ...] 

where attr is the name of the attribute and val ue is the value. 

By default, values are added. If the -r command line flag is given, the default is to 
replace existing values with the new one. It is permissible for a given attribute to 
appear more than once, for example, to add more than one value for an attribute. 
Also note that you can use a trailing double backslash ( \ \ ) to continue values 
across lines and preserve new lines in the value itself. This is useful for modifying 
QUIPU iattr attributes among others. 

attr must be preceded by a - to remove a value. The = and val ue must be omitted 
to remove an entire attribute. 

attr must be preceded by a + to add a value in the presence of the -r flag. 
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Examples 

Assuming that the file /tmp/entrymods exists and has the following contents: 
dn: cn=Modify Me, o=University of Higher Learning, c=US 

changetype: modify 

replace: mail 

mail: modme@student.of.life.edu 

add: title 
title: Grand Poobah 

add: jpegPhoto 
jpegPhoto: /tmp/modme.jpeg 

delete: description 


the command: 

ldapmodify -b -r -i /tmp/entrymods 

replaces the contents of the Modify Me entry's mail attribute with the value 
modme@student.of.life.edu, adds a title of Grand Poobah and the contents of the 
file /tmp/modme.jpeg as a jpegPhoto, and completely removes the description 
attribute. These same modifications can be performed using the older ldapmodify 
input format: 

cn=Modify Me, o=University of Higher Learning, c=US 
mai1=modme@student.of.1 ife.edu 
+title=Grand Poobah 
+jpegPhoto=/tmp/modme.jpeg 
-description 


and the command: 

ldapmodify -b -r -i /tmp/entrymods 

Assuming that the file /tmp/newentry exists and has the following contents: 
dn: cn=John Doe, o=University of Higher Learning, c=US 

objectClass: person 

cn: John Doe 

cn: Johnny 

sn: Doe 
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title: the world's most famous mythical person 


mail: johndoe@student.of. 1i fe.edu 
uid: jdoe 


the command: 
ldapadd -i /tmp/entrymods 

adds a new entry for John Doe, using the values from the file /tmp/newentry. 

Assuming that the file /tmp/newentry exists and has the contents: 
dn: cn=John Doe, o=University of Higher Learning, c=US 

changetype: delete 

the command: 
ldapmodify -i /tmp/entrymods 

removes John Doe's entry 


Notes 

If entry information is not supplied from file through the use of the -i Option, the 
ldapmodify command waits to read entries from Standard input. To break out of 
the wait, press Ctrl+C or Ctrl+D. 

Diagnostics 

Exit Status is 0 if no errors occur. Errors result in a nonzero exit Status and a 
diagnostic message being written to Standard error. 

SSL notes 

To use the SSL-related functions associated with this utility, the SSL libraries and 
tools must be installed. The SSL libraries and tools are provided with the Global 
Security Kit (GSKit), which includes RSA Security Inc. Software. 


Note: For information regarding the use of encry ption by LDAP applic ations. 


including the LDAP sample programs, see "Usage" on page 136 This section 


describes the Steps required to build the sample programs and your 
applications so they can use SSL encryption algorithms. 


The content of a client's key database file is managed with the gsk7ikm utility. For 


more information on this Java utility, see Chapter 4, "Using gsk7IKM", on page 149 


The gsk7ikm utility is used to define the set of trusted certification authorities 
(CAs) that are to be trusted by the dient. By obtaining certificates from trusted 
CAs, storing them in the key database file, and marking them as trusted, you can 
establish a trust relationship with LDAP Servers that use trusted certificates issued 
by one of the trusted CAs. The gsk7ikm utility can also be used to obtain a dient 
certificate, so that dient and Server authentication can be performed. 


If the LDAP Servers accessed by the dient use Server authentication only, it is 
sufficient to define one or more trusted root certificates in the key database file. 
With Server authentication, the dient can be assured that the target LDAP Server 
has been issued a certificate by one of the trusted CAs. In addition, all LDAP 
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transactions that flow over the SSL connection with the Server are encrypted 
including the LDAP cre dentials that are supplied on the ldapjbi nd or 


ldap_simple_bind_s (see "LDAP_BIND / UNBIND" on page 41 . For example, if 


the LDAP Server is using a high-assurance VeriSign certificate, you must obtain a 
CA certificate from VeriSign, import it into your key database file, and mark it as 
trusted. If the LDAP Server is using a self-signed Server certificate, the 
administrator of the LDAP Server can supply you with a copy of the server's 
certificate request file. Import the certificate request file into your key database file 
and mark it as trusted. 


If the LDAP Servers accessed by the dient use dient and Server authentication, it is 
necessary to: 

• Define one or more trusted root certificates in the server's key database file. This 
allows the dient to be assured that the target LDAP Server has been issued a 
certificate by one of the trusted CAs. In addition, all LDAP transactions that 
flow over the SSL connection with the Server are encrypted, including the LDAP 
credentials that are supplied on the lda p bind or ldap_simple_bind_s (see 
"LDAP_BIND / UNBIND" on page 4~l] . 

• Create a key pair using gsk7ikm and request a dient certificate from a CA. After 
receiving the signed certificate from the CA, störe the certificate in the dient key 
database file. 

See also 

ldapdelete, ldapmodrdn, ldapsearch, ldap, ldap_add, ldap_delete, ldap_modify, 
ldap_modrdn, ldap_ssl_init, ldif 


LDAPCHANGEPWD 

The LDAP modify password tool. 

Synopsis 

1dapchangepwd -D binddn -w passwd | ? -n newpassword [ ? 

[-C charset] [-d debuglevel] [-G realm] [-h ldaphost] [-K keyfile] 
[-m mechanism] [-M] [-N certificatename] [-0 maxhops] 

[-p ldapport] [-P keyfilepw] [-R] [-U username] [-v] [-V version] 
[-y proxydn ] [-Y ] [-Z] [-?] 

Description 

Sends modify password requests to an LDAP Server. 


Options 


-C charset 

Specifies that the DNs supplied as input to the ldapdelete utility are 
represented in a local character set, as specified by charset. Use -C charset 
to override the default, where strines must be supplied in UTF-8. See 


TANA character sets supported by platform" on page 184 for the specific 


charset values that are supported for each operating System platform. Note 
that the supported values for charset are the same values supported for the 
charset tag that is optionally defined in Version 1 LDIF files. 


-d debuglevel 

Set the LDAP debugging level to debuglevel. 
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-D binddn 

Use binddn to bind to the LDAP directory. binddn is a string-represented 
DN. 

-G realm 

Specify the name of the realm. When used with the -m DIGEST-MD5, the 
value is passed to the Server during the bind. 

-h Idaphost 

Specify an altemate host on which the LDAP Server is running. 

-K keyfile 

Specify the name of the SSL key database file with default extension of 
kdb. If the key database file is not in the current directory, specify the 
fully-qualified key database filename. If a key database filename is not 
specified, this utility will first look for the presence of the SSL_KEYRING 
environment variable with an associated filename. If the SSLjCEYRING 
environment variable is not defined, the default keyring file will be used, if 
present. 

A default keyring file, ldapkey.kdb, and the associated password stash file, 
ldapkey.sth, are installed in the /lib directory under LDAPHOME, where 
LDAPHOME is the path to the installed LDAP support. LDAPHOME 
varies by operating System platform: 

• AIX operating Systems - /usr/ldap 

• HP-UX operating Systems - /usr/IBMldap 

• Linux operating Systems - /usr/ldap 

• Solaris operating Systems - /usr/IBMldapc 

• Windows operating Systems - c:\Program Files\IBM\LDAP 

Note: This is the default install location. The actual LDAPHOME is 
determined during Installation. 


See Default keyring and password for more information about default key 
database files, and default Certificate Authorities. 

If a keyring database file cannot be located, a "hard-coded" set of default 
trusted certificate authority roots is used. The key database file typically 
contains one or more certificates of certificate authorities (CAs) that are 
trusted by the dient. These types of X.509 certificates are also known as 
trusted roots. For more information on ma naging an S SL key database, see 


Chapter 4, "Using gsk7IKM", on page 149| Also see the pSSL notes" on 


page 14 and "LDAP_SSL" on page 131 for more information about SSL and 


certificates. 


This parameter effectively enables the -Z switch. 

-m mechanism 

Use mechanism to specify the SASL mechanism to be used to bind to the 
Server. The ldap_sasl_bind_s() API will be used. The -m parameter is 
ignored if -V 2 is set. If -m is not specified, simple authentication is used. 

-M Manage referral objects as regulär entries. 

-n nezüpasszvord I ? 

Specifies the new password. Use the ? to generate a password prompt. 
Using this prompt prevents your password from being visible through the 
ps command. 
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-N certificatename 

Specify the label associated with the dient certificate in the key database 
file. If the LDAP Server is configured to perform Server authentication only, 
a dient certificate is not required. If the LDAP Server is configured to 
perform dient and Server authentication, a dient certificate might be 
required. certificatename is not required if a default certificate/private key 
pair has been designated as the default. Similarly, certificatename is not 
required if there is a single certificate/private key pair in the designated 
key database file. This parameter is ignored if neither -Z nor -K is 
specified. 

-O maxhops 

Specify maxhops to set the maximum number of hops that the dient 
library takes when chasing referrals. The default hopcount is 10. 

-p Idapport 

Specify an altemate TCP port where the ldap Server is listening. The 
default LDAP port is 389. If -p is not specified and -Z is specified, the 
default LDAP SSL port 636 is used. 

-P keyfilepw 

Specify the key database password. This password is required to access the 
encrypted information in the key database file, which may include one or 
more private keys. If a password stash file is associated with the key 
database file, the password is obtained from the password stash file, and 
the -P parameter is not required. This parameter is ignored if neither -Z 
nor -K is specified. 

-R Specifies that referrals are not to be automatically followed. 

-U username 

Specifies the username. This is required with -m DIGEST-MD5 and ignored 
when any other mechanism is used. The value username depends on what 
attribute the Server is configured to use. It might be a uid or any other 
value that is used to locate the entry. 

-v Use verbose mode, with many diagnostics written to Standard output. 

-V Version 

Specifies the LDAP version to be used by ldapdchangepwd when it binds 
to the LDAP Server. By default, an LDAP V3 connection is established. To 
explicitly select LDAP V3, specify -V 3. Specify -V 2 to run as an LDAP V2 
application. An application, like ldapdchangepwd, selects LDAP V3 as the 
preferred protocol by using ldap_init instead of ldap_open. 

-w passzod I ? 

Use passwd as the password for authentication. Use the ? to generate a 
password prompt. Using this prompt prevents your password from being 
visible through the ps command. 

-Z Use a secure SSL connection to communicate with the LDAP Server. The -Z 
Option is only supported when the SSL component entry, as provided by 
IBM's GSKit, is installed. 

-? Displays the syntax help for ldapchangepwd. 

Examples 

The following command changes the password for the entry named with 
commonName "John Doe" from alb2c3d4 to wxyz9876: 
ldapchangepwd -D cn=John Doe -w alb2c3d4 -n wxyz9876 
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SSL notes 

To use the SSL-related functions associated with this utility, the SSL libraries and 
tools must be installed. The SSL libraries and tools are provided with IBM's Global 
Security Kit (GSKit), which includes security Software developed by RSA Security 
Inc. 


The content of a client's key database file is managed with the gsk7ikm utility. For 


more information on this Java utility, see Chapter 4, "Using gsk7IKM", on page 149 


The gsk7ikm utility is used to define the set of trusted certification authorities 
(CAs) that are to be trusted by the dient. By obtaining certificates from trusted 
CAs, storing them in the key database file, and marking them as 'trusted', you can 
establish a trust relationship with LDAP Servers that use 'trusted' certificates 
issued by one of the trusted CAs. The gsk7ikm utility can also be used to obtain a 
dient certificate, so that dient and Server authentication can be performed. 


If the LDAP Servers accessed by the dient use Server authentication only, it is 
sufficient to define one or more trusted root certificates in the key database file. 
With Server authentication, the dient can be assured that the target LDAP Server 
has been issued a certificate by one of the trusted CAs. In addition, all LDAP 
transactions that flow over the SSL connection with the Server are encrypted 
including the LDAP credentials that are supplied on the ldapjbind or 
ldap_simple_bind_s. For example, if the LDAP Server is using a high-assurance 
VeriSign certificate, you should obtain a CA certificate from VeriSign, import it into 
your key database file, and mark it as trusted. If the LDAP Server is using a 
self-signed Server certificate, the administrator of the LDAP Server can supply you 
with a copy of the Server's certificate request file. Import the certificate request file 
into your key database file and mark it as trusted. 


If the LDAP Servers accessed by the dient use dient and Server authentication, it is 
necessary to: 

• Define one or more trusted root certificates in the key database file. This allows 
the dient to be assured that the target LDAP Server has been issued a certificate 
by one of the trusted CAs. In addition, all LDAP transactions that flow over the 
SSL connection with the Server are encrypted, including the LDAP credentials 
that are supplied on the ldapjbind or ldap_simple_bind_s. 

• Create a key pair using gsk7ikm and request a dient certificate from a CA. After 
receiving the signed certificate from the CA, störe the certificate in the dient key 
database file. 


Diagnostics 

Exit Status is 0 if no errors occur. Errors result in a nonzero exit Status and a 
diagnostic message being written to Standard error. 

See also 

ldapadd, ldapdelete, ldapexop, ldapmodify, ldapmodrdn, ldapsearch 


LDAPDELETE 


LDAP delete-entry tool 
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Synopsis 

ldapdelete [-c] [-C charset] [-d debuglevel] [-D binddn] [-G realm] [-i file] 

[-h ldaphost] [-k] [-K keyfile] [-m mechanism] [-M] [-n] [-N certificatename] 

[-0 maxhops] [-p ldapport] [-P keyfilepw] [-R] [-s] [-U username] [-v] [-V version] 
[-w passwd | ?] [-y proxydn] [-Y] [-Z] [dn] ... 


Description 

ldapdelete is a command-line interface to the ldap_delete library call. 


ldapdelete opens a Connection to an LDAP Server, binds, and deletes one or more 
entries. If one or more Distinguished Name (DN) arguments are prov ided, entries 


with those DNs are deleted. Each DN is a s tring-represented DN (see Appendix C, 


'LDAP distinguished names", on page 1791. If no DN arguments are provided, a 


list of DNs is read from Standard input, or from file if the -i flag is used. 


To display syntax help for ldapdelete, type: 
ldapdelete -? 


Options 

-c Continuous Operation mode. Errors are reported, but ldapdelete continues 
with modifications. Otherwise the default action is to exit after reporting 
an error. 


-C charset 

Specifies that the DNs supplied as input to the ldapdelete utility are 
represented in a local character set, as specified by charset. Use -C charset 
to override the default, where strings must be supplied in UTF-8. See 


TANA character sets supported by platform" on page 184|for the specific 


charset values that are supported for each operating System platform. Note 
that the supported values for charset are the same values supported for the 
charset tag that is optionally defined in Version 1 LDIF files. 

-d debuglevel 

Set the LDAP debugging level to debuglevel. 


-D binddn 

Use bin ddn to bind to the LDAP directory. binddn is a string-repr esented 


DN. See Appendix C, "LDAP distinguished names", on page 179 


-G realm 

Specify the name of the realm. When used with the -m DIGEST-MD5, the 
value is passed to the Server during the bind. 


-h ldaphost 

Specify an altemate host on which the LDAP Server is running. 

-ifile Read a series of lines from file, performing one LDAP delete for each line 
in the file. Each line in the file must contain a single distinguished name. 

-k Specifies to use Server administration control. 

-K keyfile 

Specify the name of the SSL key database file with default extension of 
kdb. If the key database file is not in the current directory, specify the 
fully-qualified key database filename. If a key database filename is not 
specified, this utility first looks for the presence of the SSL_KEYRING 
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environment variable with an associated filename. If the SSLjCEYRING 
environment variable is not defined, the default keyring file is used, if 
present. 

A default keyring file (ldapkey.kdb), and the associated password stashfile 
(ldapkey.sth), are installed in the /lib directory under LDAPHOME, where 
LDAPHOME is the path to the installed LDAP support. LDAPHOME 
varies by operating System platform: 

Windows 

c:\Program Files\IBM\LDAP 
AIX /usr/ldap 
Solaris 

/opt/IBMldapc 
Linux /usr/ldap 
HP-UX 

/ usr/IBMldap 


Note: This is the default installation location. The actual LDAPHOME is 
determined during installatio n. 

See Default keyring and password for more information about default key 
database files and default CAs. 


If a keyring database file cannot be located, a hard-coded set of default 
trusted certificate authority roots is used. The key database file typically 
contains one or more certificates of CAs that are trusted by the dient. 
These types of X.509 certificates are also known as tru sted roots. For mor e 


information about mana ging an SSL key database, see IChapter 4, "Using 


gskTIKM^^onjaageJ^ 


Also see the 


'LDAP SSL" on page 131 


'SSL notes" on page 18 


and 


for more information about SSL and certificates. 


This parameter effectively enables the -Z switch. 

-m mechanism 

Use mechanism to specify the Simple Authentication Security Layer (SASL) 
mechanism to be used to bind to the Server. The ldap_sasl_bind_s() API is 
used. The -m parameter is ignored if -V 2 is set. If -m is not specified, 
simple authentication is used. 

-M Manage referral objects as regulär entries. 

-N certificatename 

Specify the label associated with the dient certificate in the key database 
file. If the LDAP Server is configured to perform Server authentication only, 
a dient certificate is not required. If the LDAP Server is configured to 
perform dient and Server authentication, a dient certificate might be 
required. certificatename is not required if a default certificate/private key 
pair has been designated as the default. Similarly, certificatename is not 
required if there is a single certificate/private key pair in the designated 
key database file. This parameter is ignored if neither -Z nor -K is 
specified. 

-O maxhops 

Specify maxhops to set the maximum number of hops that the dient 
library takes when chasing referrals. The default hopcount is 10. 
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-p Idapport 

Specify an altemate TCP port where the ldap Server is listening. The 
default LDAP port is 389. If -p is not specified and -Z is specified, the 
default LDAP SSL port 636 is used. 

-P keyfilepzv 

Specify the key database password. This password is required to access the 
encrypted information in the key database file, which can include one or 
more private keys. If a password stash file is associated with the key 
database file, the password is obtained from the password stash file, and 
the -P parameter is not required. This parameter is ignored if neither -Z 
nor -K is specified. 

-R Specifies that referrals are not to be automatically followed. 

-s Use this Option to delete the subtree rooted at the specified entry. 

-U username 

Specifies the username. This is required with -m DIGEST-MD5 and ignored 
when any other mechanism is used. The value username depends on what 
attribute the Server is configured to use. It might be a uid or any other 
value that is used to locate the entry. 

-v Use verbose mode, with many diagnostics written to Standard output. 

-V Version 

Specifies the LDAP version to be used by ldapdelete when it binds to the 
LDAP Server. By default, an LDAP V3 connection is established. To 
explicitly select LDAP V3, specify -V 3. Specify -V 2 to run as an LDAP V2 
application. An application, such as ldapdelete, selects LDAP V3 as the 
preferred protocol by using ldap_init instead of ldap_open. 


-w passwd I ? 

Use passwd as the password for authentication. Use the ? to generate a 
password prompt. Using this prompt prevents your password from being 
visible through the ps command. 

-Z Use a secure SSL connection to communicate with the LDAP Server. The -Z 
Option is only supported when the SSL componentry, as provided by the 
GSKit, is installed. 


-dn 


Specifies one or more DN arguments. Each DN must be a _ 

string-rep resented DN. See Appendix C, "LDAP distinguished names", on 
page 179] 


Examples 

The following command attempts to delete the entry named with commonName 
Delete Me directly below the University of Life organizational entry. It might be 
necessary to supply a binddn and passwd for deletion to be allowed (see the -D 
and -w options). 

ldapdelete "cn=Delete Me, o=University of Life, c=US" 


Notes™ 

If no DN arguments are provided, the ldapdelete command waits to read a list of 
DNs from Standard input. To break out of the wait, press Ctrl+C or Ctrl+D. 


Diagnostics 

Exit Status is 0 if no errors occur. Errors result in a nonzero exit Status and a 
diagnostic message being written to Standard error. 
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SSL notes 


See "SSL notes" on page 10 


See also 

ldapadd, ldapchangepwd, ldapmodify, ldapmodrdn, ldapsearch, ldap, ldap_add, 
ldap_delete, ldap_modify, ldap_modrdn, ldap_ssl_init, ldif 


LDAPEXOP 


The LDAP extended Operation tool 

Synopsis 

Idapexop [-C charset] [-d debuglevel] [-D binddn] [-e] [-G realm] [-h ldaphost] 

[-hei p] [-K keyfile] [-m mechanism] [-N certi ficatename] 

[-p Idapport] [-P keyfilepw] [-?] [-U username] [-v] [-w passwd | ?] [-Y] [-Z] 

-op {cascrepl | clearlog | controlqueue | controlrepl | getlogsize | 
quiesce | readconfig | readlog} 

Description 

The Idapexop utility is a command-line interface that provides the capability to 
bind to a directory and issue a single extended Operation along with any data that 
makes up the extended Operation value. 

The Idapexop utility Supports the Standard host, port, SSL, and authentication 
options used by all of the LDAP client Utilities. In addition, a set of options is 
defined to specify the Operation to be performed, and the arguments for each 
extended Operation 

To display syntax help for Idapexop, type: 

Idapexop -? 


or 

Idapexop -help 


Options 

The options for the Idapexop command are divided into two categories: 

• General options that specify how to connect to the directory Server. These 
options must be specified betöre Operation specific options. 

• Extended Operation Option that identifies the extended Operation to be 
performed. 


General options 

These options specify the methods of connecting to the Server and must be 
specified betöre the -op Option. 


-C charset 

Specifies that the DNs supplied as input to the Idapexop utility are 
represented in a local character set, as specified by charset. Use -C charset 
to override the default, where strings must be supplied in UTF-8. See 


TANA character sets supported by platform" on page 184 for the specific 


charset values that are supported for each operating System platform. Note 
that the supported values for charset are the same values supported for the 
charset tag that is optionally defined in Version 1 LDIF files. 
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-d debuglevel 

Set the LDAP debugging level to debuglevel. 

-D binddn 

Use binddn to bind to the LDAP directory. binddn is a string-represented 
DN. 

-e Displays the LDAP library version information and then exits. 

-G realm 

Specify the name of the realm. When used with the -m DIGEST-MD5, the 
value is passed to the Server during the bind. 

-h Idaphost 

Specify an altemate host on which the LDAP Server is running. 

-help Displays the usage. 

-K keyfile 

Specify the name of the SSL key database file with default extension of 
kdb. If the key database file is not in the current directory, specify the 
fully-qualified key database filename. If a key database filename is not 
specified, this utility will first look for the presence of the SSL_KEYRING 
environment variable with an associated filename. If the SSLjCEYRING 
environment variable is not defined, the default keyring file will be used, if 
present. 

A default keyring file that is, ldapkey.kdb, and the associated password 
stash file that is, ldapkey.sth, are installed in the /lib directory under 
LDAPHOME, where LDAPHOME is the path to the installed LDAP 
support. LDAPHOME varies by operating System platform: 

• AIX operating Systems - /usr/ldap 

• HP-UX operating Systems - /usr/IBMldap 

• Linux operating Systems - /usr/ldap 

• Solaris operating Systems - /usr/IBMldapc 

• Windows operating Systems - c:\Program Files\IBM\LDAP 


Note: This is the default install location. The actual LDAPHOME is 
determined during Installation. 


See Default keyring and password for more information about default key 
database files, and default Certificate Authorities. 


If a keyring database file cannot be located, a "hard-coded" set of default 
trusted certificate authority roots is used. The key database file typically 
contains one or more certificates of certificate authorities (CAs) that are 
trusted by the dient. These types of X.509 certificates are also known as 
tru sted roots. For more information about man aging an SS L key database. 


see 


Chapter 4, "Using gsk7IKM", on page 149 


page 22 and 
certificates. 


'LDAP SSL" on page 131 


Also see the 


'SSL notes" on 


for more information about SSL and 


This parameter effectively enables the -Z switch. 

-m mechanism 

Use mechanism to specify the SASL mechanism to be used to bind to the 
Server. The ldap_sasl_bind_s() API will be used. The -m parameter is 
ignored if -V 2 is set. If -m is not specified, simple authentication is used. 
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-N certificatename 

Specify the label associated with the dient certificate in the key database 
file. If the LDAP Server is configured to perform Server authentication only, 
a dient certificate is not required. If the LDAP Server is configured to 
perform dient and Server Authentication, a dient certificate might be 
required. certificatename is not required if a default certificate/private key 
pair has been designated as the default. Similarly, certificatename is not 
required if there is a single certificate/private key pair in the designated 
key database file. This parameter is ignored if neither -Z nor -K is 
specified. 

-p Idapport 

Specify an altemate TCP port where the LDAP Server is listening. The 
default LDAP port is 389. If -p is not specified and -Z is specified, the 
default LDAP SSL port 636 is used. 

-P keyfilepiv 

Specify the key database password. This password is required to access the 
encrypted information in the key database file, which may include one or 
more private keys. If a password stash file is associated with the key 
database file, the password is obtained from the password stash file, and 
the -P parameter is not required. This parameter is ignored if neither -Z 
nor -K is specified. 

-? Displays the usage. 

-U username 

Specifies the username. This is required with -m DIGEST-MD5 and ignored 
when any other mechanism is used. The value username depends on what 
attribute the Server is configured to use. It might be a uid or any other 
value that is used to locate the entry. 

-v Use verbose mode, with many diagnostics written to Standard output. 

-w passwd I ? 

Use passwd as the password for authentication. Use the ? to generate a 
password prompt. Using this prompt prevents your password from being 
visible through the ps command. 

-Z Use a secure SSL connection to communicate with the LDAP Server. The -Z 
Option is only supported when the SSL component entry, as provided by 
IBM's GSKit, is installed. 

Extended operations Option 

The -op extended-op Option identifies the extended Operation to be performed. The 
extended Operation can be one of the following values: 

• cascrepl: cascading control replication extended Operation. The requested action 
is applied to the specified Server and also passed along to all replicas of the 
given subtree. If any of these are forwarding replicas, they pass the extended 
Operation along to their replicas. The Operation cascades over the entire 
replication topology. 

-action quiesce I unquiesce I replnow I wait 

This is a required attribute that specifies the action to be performed. 

quiesce 

No further Updates are allowed, except by replication. 

unquiesce 

Resume normal Operation, dient Updates are accepted. 
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replnow 

Replicate all queued changes to all replica Servers as soon as 
possible, regardless of schedule. 

wait Wait for all Updates to be replicated to all replicas. 

-rc contextDn 

This is a required attribute that specifies the root of the subtree. 

-timeout secs 

This is an optional attribute that if present, specifies the timeout period 
in seconds. If not present, or 0, the Operation waits indefinitely. 

Example: 

ldapexop -op cascrepl -action -quiesce -rc "o=acme,c=us" -timeout 60 
clearlog: clear log file extended Operation 

-log audit I bulkload I cli I slapd I ibmdiradm 

This is a required attribute that specifies the log file to be cleared. 

Example: 

ldapexop -op clearlog -log audit 
controlqueue: control queue extended Operation 

-skip all I change-id 

This is a required attribute. 

- all indicates to skip all pending changes for this agreement. 

- change-id identifies the single change to be skipped. If the Server is 
not currently replicating this change, the request fails. 

-ra agreementDn 

This is a required attribute that specifies the DN of the replication 
agreement. 

Examples: 

ldapexop -op controlqueue -skip all -ra "cn=server3, 

i bm-repl icaSubentry=masterl-id,ibm-replicaGroup=default, 
o=acme,c=us" 

ldapexop -op controlqueue -skip 2185 -ra "cn=server3, 

ibm-replicaSubentry=masterl-id,ibm-replicaGroup=default, 
o=acme,c=us" 

controlrepl: control replication extended Operation 

-action suspend I resume I replnow 

This is a required attribute that specifies the action to be performed. 

-rc contextDn I -ra agreementDn 

The -rc contextDn is the DN of the replication context. The action is 
performed for all agreements for this context. The -ra agreementDn is the 
DN of the replication agreement. The action is performed for the 
specified replication agreement. 

Example: 

ldapexop -op controlrepl -action suspend -ra "cn=server3, 

i bm-repl icaSubentry=masterl-id,ibm-replicaGroup=default, 
o=acme,c=us" 

getlogsize: request log file size extended Operation 
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-log audit I bulkload I cli I slapd I ibmdiradm 

This is a required attribute that specifies the log file to be queried The 
size of the log file, in lines, is written to Standard output. 

Example: 

ldapexop -op getlogsize -log slapd 
2000 lines 

• quiesce: quiesce or unquiesce subtree extended Operation 
-rc contextDn 

This is a required attribute that specifies the DN of the replication 
context (subtree) to be quiesced or unquiesced. 

-end This is an optional attribute that if present, specifies to unquiesce the 
subtree. If not specified the default is to quiesce the subtree. 

Examples: 

ldapexop -op quiesce -rc "o=acme,c=us" 

ldapexop -op quiesce -end -rc "o=ibm,c=us" 

• readconfig: reread configuration file extended Operation 

-scope entire I single entry DN attribute 
This is a required attribute. 

- entire indicates to reread the entire configuration file. 

- single means to read the single entry and attribute specified. 


Examples: 

ldapexop -op readconfig -scope entire 

ldapexop -op readconfig -scope single "cn=configuration" ibm-slapdAdminPW 
• readlog: request lines from log file extended Operation 

-log audit I bulkload I cli I slapd I ibmdiradm 

This is a required attribute that specifies the log file to be queried. 

-lines first last I all 

This is a required attribute that specifies either the first and last lines to 
be read from the file or all lines. Lines are numbered starting at 0. The 
specified lines are written to Standard output. 

Examples: 

ldapexop -op readlog -log audit -lines 10 20 
ldapexop -op readlog -log slapd -lines all 


Notes 

If no DN arguments are provided, the ldapdexop command waits to read a list of 
DNs from Standard input. To break out of the wait, use Ctrl+C or Ctrl+D. 

SSL notes 

To use the SSL-related functions associated with this utility, the SSL libraries and 
tools must be installed. The SSL libraries and tools are provided with IBM's Global 
Security Kit (GSKit), which includes security Software developed by RSA Security 
Inc. 
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The content of a client's key database file is managed with the gsk7ikm utility. For 


more information on this Java utility, see Chapter 4, "Using gsk7IKM", on page 149 


The gsk7ikm utility is used to define the set of trusted certification authorities 
(CAs) that are to be trusted by the dient. By obtaining certificates from trusted 
CAs, storing them in the key database file, and marking them as 'trusted', you can 
establish a trust relationship with LDAP Servers that use 'trusted' certificates 
issued by one of the trusted CAs. The gsk7ikm utility can also be used to obtain a 
dient certificate, so that dient and Server authentication can be performed. 


If the LDAP Servers accessed by the dient use Server authentication only, it is 
sufficient to define one or more trusted root certificates in the key database file. 
With Server authentication, the dient can be assured that the target LDAP Server 
has been issued a certificate by one of the trusted CAs. In addition, all LDAP 
transactions that flow over the SSL connection with the Server are encrypted 
including the LDAP credentials that are supplied on the ldap_bind 0 r 
ldap_simple_bind_s. For example, if the LDAP Server is using a high-assurance 
VeriSign certificate, you should obtain a CA certificate from VeriSign, import it into 
your key database file, and mark it as trusted. If the LDAP Server is using a 
self-signed Server certificate, the administrator of the LDAP Server can supply you 
with a copy of the server's certificate request file. Import the certificate request file 
into your key database file and mark it as trusted. 


If the LDAP Servers accessed by the dient use dient and Server authentication, it is 
necessary to: 

• Define one or more trusted root certificates in the key database file. This allows 
the dient to be assured that the target LDAP Server has been issued a certificate 
by one of the trusted CAs. In addition, all LDAP transactions that flow over the 
SSL connection with the Server are encrypted, including the LDAP credentials 
that are supplied on the ldapjbind or ldap_simple_bind_s. 

• Create a key pair using gsk7ikm and request a dient certificate from a CA. After 
receiving the signed certificate from the CA, störe the certificate in the dient key 
database file. 


Diagnostics 

Exit Status is 0 if no errors occur. Errors result in a nonzero exit Status and a 
diagnostic message being written to Standard error. 

See also 

ldapadd, ldapchangepwd, ldapdelete, ldapmodify, ldapmodrdn, ldapsearch 


LDAPMODRDN 


LDAP modify-entry RDN tool 

Synopsis 

ldapmodrdn [-c] [-C charset] [-d debuglevel] 

[-D binddn] [-G realm] [-i file] [-k] [-K keyfile] 

[-m mechanism] [-M] [-n] [-N certificatename] 

[-0 hopcount] [-p ldapport] [-P keyfilepw] [-r] 

[-R] [-U username] [-v] [-V] [-w passwd] [-?] [-y proxydn] [-Y] [-Z] 

[dn newrdn [ [-i file]] 

Description 

ldapmodrdn is a command-line interface to the ldap_modrdn library call. 


Chapter 2. LDAP Utilities 23 




ldapmodrdn opens a connection to an LDAP Server, binds, and modifies the RDN 
of entries. The entry information is read from Standard input, from file through the 
use of the - i Option, or from the command-line pair dn and rdn. 


See Appendix C, "LDAP distinguished names", on page 179 


RDNs (Relative Distinguished Names) and DNs (Distinguis 


for information about 
red Names). 


To display syntax help for ldapmodrdn, type: 
ldapmodrdn -? 


Options 


-c Continuous Operation mode. Errors are reported, but ldapmodrdn 

continues with modifications. Otherwise the default action is to exit after 
reporting an error. 


-C charset 

Specifies that the Strings supplied as input to the ldapmodrdn utility are 
represented in a local character set, as specified by charset. Use -C charset 
to override the default, where strings must be supplied in UTF-8. See 


TANA character sets supported by platform" on page 184|for the specific 


charset values that are supported for each operating System platform. Note 
that the supported values for charset are the same values supported for the 
charset tag that is optionally defined in Version 1 LDIF files. 


-d debuglevel 

Set the LDAP debugging level to debuglevel. 


-D binddn 

Use binddn to bind to the LDAP directory. binddn must be a 


string-rep resented DN (see | Appendix C, 
page 179| ). 


'LDAP distinguished names", on 


-G realm 

Specify the name of the realm. When used with the -m DIGEST-MD5, the 
value is passed to the Server during the bind. 


-h Idaphost 

Specify an altemate host on which the LDAP Server is running. 


-i file Read the entry modification information from file instead of from Standard 
input or the command-line (by specifying rdn and newrdn). 


-k Indicates that the Server administration control should be used. 


-K keyfile 

Specify the name of the SSL key database file (with default extension of 
kdb). If the key database file is not in the current directory, specify the 
fully-qualified key database filename. If a key database filename is not 
specified, this utility first looks for the presence of the SSLjCEYRING 
environment variable with an associated filename. If the SSLjCEYRING 
environment variable is not defined, the default keyring file is used, if 
present. 

A default keyring file (ldapkey.kdb) and the associated password stashfile 
(ldapkey.sth) are installed in the /lib directory under LDAPHOME, where 
LDAPHOME is the path to the installed LDAP support. LDAPHOME 
varies by operating System platform: 

Windows 

c:\Program Files\IBM\LDAP 
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AIX /usr/ldap 
Solaris 

/opt/IBMldapc 
Linux /usr/ldap 
HP /usr/IBMldap 


Note: This is the default installation location. The actual LDAPHOME is 
determined during installatio n. 

See Default keyring and password for more Information about default key 
database files, and default CAs. 


If a keyring database file cannot be located, a hard-coded set of default 
trusted certificate authority roots is used. The key database file typically 
contains one or more certificates of CAs that are trusted by the dient. 
These types of X.509 certificates are also known as trusted roots. For m ore 


gsk7IKM", on page 149 

“ö — 
Also see 

"SSL notes" on page 27 and 

"LDAP SSL" 


on page 131| for more information about SSL and certificates. 


This parameter effectively enables the -Z switch, 
m mechanism 

Use mechanism to specify the SASL mechanism to be used to bind to the 
Server. The ldap_sasl_bind_s() API is used. The -m parameter is ignored if 
-V 2 is set. If -m is not specified, simple authentication is used. 

M Manage referral objects as regulär entries. 

n Show what would be done, but don't actually modify entries. Useful for 
debugging in conjunction with -v. 

N certificatename 

Specify the label associated with the dient certificate in the key database 
file. Note that if the LDAP Server is configured to perform Server 
authentication only, a dient certificate is not required. If the LDAP Server is 
configured to perform dient and Server authentication, a dient certificate 
might be required. certificatename is not required if a default 
certificate/private key pair has been designated as the default. Similarly, 
certificatename is not required if there is a single certificate/private key 
pair in the designated key database file. This parameter is ignored if 
neither -Z nor -K is specified. 

O hopcount 

Specify hopcount to set the maximum number of hops that the dient 
library takes when chasing referrals. The default hopcount is 10. 

p Idapport 

Specify an altemate TCP port where the ldap Server is listening. The 
default LDAP port is 389. If not specified and -Z is specified, the default 
LDAP SSL port 636 is used. 

P keyfilepzü 

Specify the key database password. This password is required to access the 
encrypted information in the key database file, which can include one or 
more private keys. If a password stash file is associated with the key 
database file, the password is obtained from the password stash file, and 
the -P parameter is not required. This parameter is ignored if neither -Z 
nor -K is specified. 
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-r Remove old RDN values from the entry. Default action is to keep old 
values. 

-R Specifies that referrals are not to be automatically followed. 

-U username 

Specifies the username. This is required with -m DIGEST-MD5 and ignored 
when any other mechanism is used. The value username depends on what 
attribute the Server is configured to use. It might be a uid or any other 
value that is used to locate the entry. 

-v Use verbose mode, with many diagnostics written to Standard output. 

-V Specifies the LDAP version to be used by ldapmodrdn when it binds to 

the LDAP Server. By default, an LDAP V3 connection is established. To 
explicitly select LDAP V3, specify -V 3. Specify -V 2 to run as an LDAP V2 
application. An application, such as ldapmodrdn, selects LDAP V3 as the 
preferred protocol by using ldap_init instead of ldap_open. 

-w passzvd I ? 

Use passwd as the password for authentication. Use the ? to generate a 
password prompt. Using this prompt prevents your password from being 
visible through the ps command. 

-Z Use a secure SSL connection to communicate with the LDAP Server. The -Z 
Option is only supported when the SSL componentry, as provided by the 
GSKit, is installed. 


dn newrdn 

See the following section, 
information. 


'Input format for dn newrdn" for more 


Input format for dn newrdn 

It the command-line arguments dn and newrdn are given, newrdn replaces the RDN 
of the entry specified by the DN, dn. Otherwise, the contents of file (or Standard 
input it no - i flag is given) consists of one or more pairs: 

Distinguished Name (DN) 

Relative Distinguished Name (RDN) 


One or more blank lines may be used to separate each DN and RDN pair. 

Examples 

Assuming that the file /tmp / entrymods exists and contains the following: 

cn=Modify Me, o=University of Life, c=US 
cn=The New Me 

the command: 

ldapmodrdn -r -i /tmp/entrymods 

changes the RDN of the Modify Me entry from Modify Me to The New Me and the old 
cn, Modify Me is removed. 


Notes 

It entry information is not supplied from file through the use of the -i Option or 
from the command-line pair dn and rdn, the ldapmodrdn command waits to read 
entries from Standard input. To break out of the wait, press Ctrl+C or Ctrl+D. 
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Diagnostics 

Exit Status is 0 if no errors occur. Errors result in a nonzero exit Status and a 
diagnostic message being written to Standard error. 


SSL notes 


See 


'SSL notes" on page 10 


See also 

ldapadd, ldapdelete, ldapsearch, ldap, ldap_add, ldap_delete, ldap_modify, 
ldap_modrdn / ldap_ssl_init, ldif 


LDAPSEARCH 


LDAP search tool and sample program 

Synopsis 

ldapsearch [-a deref] [-A] [-b searchbase] [-B] [-C charset] 

[-d debuglevel] [-D binddn] [-G realm] [-i file] filter [attrs...] [-F sep] 
[-h ldaphost] [-K keyfile] [-1 timelimit] [-L] [-m mechanism] 

[-M] [-n] [-N certificatename] [-o attributename] [-0 hopcount] 

[-p ldapport] [-P keyfilepw] [-q pagesize] [-R] [-s scope ] 

[-t] [-T seconds] [-U username] [-v] [-V version] [-w bindpasswd] 

[-y proxydn] [-Y] [-z sizelimit] [-Z] 

[-9 p] [-9 s] 


Description 

ldapsearch is a command-line interface to the ldap_search library call. 


ldapsearch opens a connection to an LDAP Server, binds, and performs a search 
using the filter. The filter must conform to the string representation for LDAP 
filters (see "LDAP_SEARCH" on page 111 for more information about filters). 


If ldapsearch finds one or more entries, the attributes specified by attrs are 
retrieved and the entries and values are printed to Standard output. If no attrs are 
listed, all attributes are returned. 


To display syntax help for ldapsearch, type ldapsearch -? 

Options 

-a deref 

Specify how aliases dereferencing is done. deref must be one of the 
following: 

never Aliases are never dereferenced. 

This is the default. 


always 

search 

find 


Aliases are always dereferenced. 

Aliases are dereferenced when searching. 

Aliases are dereferenced only when locating the base object for the 
search. 
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-A Retrieve attributes only, no values. This is useful when you just want to 
see if an attribute is present in an entry and are not interested in the 
specific values. 

-b s earchbase 

Use searchbase as the starting point for the search instead of the default. If 
-b is not specified, this utility examines the LDAP_BASEDN environment 
variable for a searchbase definition. If neither is set, the default base is set 


-B Do not suppress display of non-ASCII values. This is useful when dealing 
with values that appear in altemate characters sets such as ISO-8859.1. This 
Option is implied by the -L Option. 


-C charset 

Specifies that strings supplied as input to the ldapsearch utility are 
represented in a local character set, as specified by charset. String input 
includes the filter, the bind DN, and the base DN. Similarly, when 
displaying data, ldapsearch converts data received from the LDAP Server 
to the specified character set. Use -C charset to override the default, where 
strings must be supplied in UTF-8. Also, if the -C Option and the -L Option 
are both specified, input is assumed to be in the specified character set, but 
output from ldapsearch is always preserved in its UTF-8 representation, or 
a base-64 encoded representation of the data when non-printable characters 
are detected. This is the case because Standard LDIF files contain UTF-8 or 
base-64-encoded UTF-8 representations of string da ta only. See 


TANA 


character sets supported by platform" on page 184| for the specific charset 


values that are supported for each operating System platform. Note that 
the supported values for charset are the same values supported for the 
charset tag that is optionally defined in Version 1 LDIF files. 


-d debuglevel 

Set the LDAP debugging level to debuglevel. 


-D binddn 

Use binddn to bind to the LDAP directory. binddn must be a 


-e 


string-rep resented DN. See Appendix C, "LDAP distinguished names", on 


page 179| for more information. 

Displays the LDAP library Version information and exits. 


-G realm 

Specify the name of the realm. When used with the -m DIGEST-MD5, the 
value is passed to the Server during the bind. 

-i file Read a series of lines from/i7e, performing one LDAP search for each line. 

In this case, the filter given on the command line is treated as a pattern 
where the first occurrence of %s is replaced with a line from file. If file is a 
single hyphen ( -) character, then the lines are read from Standard input. 

filter Specifies a string representation of the filter to apply in the search. Simple 
filters can be specified as attributetype=attributevalue. More complex filters 
are specified using a prefix notation according to the following Backus 
Naur Form (BNF): 

<filter> (’<filtercomp>’)’ 

<filtercomp> ::= <and>\<or>\<not>\<simple> 

<and> ::= <filterlist> 

<or> :: = <filterlist> 

<not> ::= ’P <filter> 
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<filterlist> ::= <filter>\<filter><filtertype> 
<simple> ::= <attributetype><filtertype> 
<attributevalue> 

<filtertype> ’=’ |’~=’ |’<=’ |’>=’ 


The '~=' construct is used to specify approximate matching. The 
representation for <attributet\me> and <attributevahie > are as described in 


RFC 2252, LDAP V3 Attribute Syntax Definitions" In addition. 


<attributevalue> can be a single 
can contain text and asterisks ( 
matching. 


to achieve an attribute existence test, or 
) interspersed to achieve substring 


For example, the filter "(mail=*)" finds any entries that have a mail 
attribute. The filter "(mail=*@student.of. life.edu)" finds any entries that 
have a mail attribute ending in the specified string. To put parentheses in a 
filter, escape them with a backslash ( \ ) character. 


Note: A filter like "(cn=Bob *)", where there is a space between Bob and 
the asterisk ( * ), matches "Bob Carter" but not "Bobby Carter" in 
IBM Directory Server. The space between "Bob" and the wildcard 
character ( * ) affects the outcome of a search using filters. 


See |"RFC 2254, A String Representation of LDAP Search Filters"| for a more 
complete description of allowable filters. 


F sep Use sep as the field Separator between attribute names and values. The 
default Separator is equals ( = ), unless the -L flag has been specified, in 
which case this Option is ignored. 


h Idaphost 

Specify an alternate host on which the LDAP Server is running. 

K keyfile 

Specify the name of the SSL key database file with default extension of 
.kdb. If the key database file is not in the current directory, specify the 
fully-qualified key database filename. If a key database filename is not 
specified, this utility first looks for the presence of the SSLjCEYRING 
environment variable with an associated filename. If the SSLjCEYRING 
environment variable is not defined, the default keyring file is used, if 
present. 


A default keyring file (ldapkey.kdb) and the associated password stashfile 
(ldapkey.sth) are installed in the /lib directory under LDAPHOME, where 
LDAPHOME is the path to the installed LDAP support. LDAPHOME 
varies by operating System platform: 


Windows 

c:\Program Files\IBM\LDAP 
AIX /usr/ldap 

Solaris 

/opt/IBMldapc 
Linux / usr/ldap 
HP /usr/IBMldap 
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Note: This is the default installation location. The actual LDAPHOME is 
determined during installatio n. 

See Default keyring and password for more Information about default key 
database files, and default CAs. 


If a keyring database file cannot be located, a hard-coded set of default 
trusted certificate authority roots is used. The key database file typically 
contains one or more certificates of CAs that are trusted by the dient. 
These types of X.509 certificates are also known as trusted roots. For m ore 


gsk7IKM", on page 149 

“ö — 
Also see 

"SSL notes" on page 35 

and 

"LDAP_SSL" 


on page131 


for more information about SSL and certificates. 


This parameter effectively enables the -Z switch. 

-1 timelimit 

Wait at most timelimit seconds for a search to complete. 


-L Display search results in ldif format. This Option also turns on the -B 
Option, and causes the -F Option to be ignored. 


-m mechanism 

Use mechanism to specify the SASL mechanism to be used to bind to the 
Server. The ldap_sasl_bind_s() API is used. The -m parameter is ignored if 
-V 2 is set. If -m is not specified, simple authentication is used. 

-M Manage referral objects as regulär entries. 

-n Show what would be done, but do not actually modify entries. Useful for 
debugging in conjunction with -v. 


-N certificatename 

Specify the label associated with the dient certificate in the key database 
file. 


Note: If the LDAP Server is configured to perform Server authentication 
only, a dient certificate is not required. If the LDAP Server is 
configured to perform dient and Server Authentication, a dient 
certificate might be required. certificatename is not required if a 
default certificate/private key pair has been designated as the 
default. Similarly, certificatename is not required if there is a single 
certificate/private key pair in the designated key database file. This 
parameter is ignored if neither -Z nor -K is specified. 

-o attributename 

To specify an attribute to use for sort criteria of search results, you can use 
the -o (order) parameter. You can use multiple -o parameters to further 
define the sort order. In the following example, the search results are 
sorted first by surname (sn), then by given name (givenname), with the 
given name being sorted in reverse (descending) order as specified by the 
prefixed minus sign ( - ): 

-o sn -o -givenname 

Thus, the syntax of the sort parameter is as follows: 

[-]<attribute name>[:<matching rule 01D>] 

where 

• attri bute name is the name of the attribute you want to sort by. 
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• matching rule 01D is the optional OID of a matching rule that you want 
to use for sorting. 

• The minus sign ( - ) indicates that the results must be sorted in reverse 
Order. 

The default ldapsearch Operation is to not sort the returned results. 

Note: The dient uses the -o parameter to request that the Server sort the 
results. If the Server does not support sorting, you must also specify 
the -9 s Option to if you want the search results to be returned 
unsorted. If you do not specify this Option and the Server does not 
support sorting, the request will fail. 

O hopcount 

Specify hopcount to set the maximum number of hops that the dient 
library takes when chasing referrals. The default hopcount is 10. 

p Idapport 

Specify an alternate TCP port where the LDAP Server is listening. The 
default LDAP port is 389. If an alternate TCP port is not specified, and -Zis 
specified, the default LDAP SSL port 636 is used. 

P keyfilepw 

Specify the key database password. This password is required to access the 
encrypted information in the key database file (which can include one or 
more private keys). If a password stash file is associated with the key 
database file, the password is obtained from the password stash file, and 
the -P parameter is not required. This parameter is ignored if neither -Z 
nor -K is specified. 

q pagesize 

To specify paging of search results, two new parameters can be used: -q 
(query page size), and -T (time between searches, in seconds). In the 
following example, the search results return a page (25 entries) at a time, 
every 15 seconds, until all the results for that search are returned. The 
ldapsearch dient handles all connection continuation for each paged results 
request for the life of the search Operation. 

-q 25 -T 15 

If the -v (verbose) parameter is specified, ldapsearch lists how many 
entries have been returned so far after each page of entries returned from 
the Server; for example, 30 total entries have been returned. 

Multiple -q parameters are enabled such that you can specify different 
page sizes throughout the life of a single search Operation. In the following 
example, the first page is 15 entries, the second page is 20 entries, and the 
third parameter ends the paged result/search Operation: 

-q 15 -q 20 -q 0 

In the following example, the first page is 15 entries, and all the rest of the 
pages are 20 entries, continuing with the last specified -q value until the 
search Operation completes: 

-q 15 -q 20 

The default ldapsearch Operation is to return all entries in a single request. 
No paging is done for the default ldapsearch Operation. 
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Note: The dient uses the -q parameter to request that the Server page the 
results. If the Server does not support paging, you must also specify 
the -9 p Option to if you want the search results to be returned 
unpaged. If you do not specify this Option and the Server does not 
Support paging, the request will fail. 

-R Specifies that referrals are not to be automatically followed. 

-s scope 

Specify the scope of the search. scope must be one of the following: 
base Specifies a base object search. 

one Specifies a one-level search. 

sub Specifies a subtree search. 

This is the default. 

-t Write retrieved values to a set of temporary files. This is useful for dealing 
with non-ASCII values such as jpegPhoto or audio. 

-T seconds 

Time between searches (in seconds). The -T Option is only supported when 
the -q Option is specified. 

-U username 

Specifies the username. This is required with -m DIGEST-MD5 and ignored 
when any other mechanism is used. The value username depends on what 
attribute the Server is configured to use. It might be a uid or any other 
value that is used to locate the entry. 

-v Use verbose mode, with many diagnostics written to Standard output. 

-V Version 

Specifies the LDAP version to be used by ldapmodify when it binds to the 
LDAP Server. By default, an LDAP V3 connection is established. To 
explicitly select LDAP V3, specify -V 3. Specify -V 2 to run as an LDAP V2 
application. An application, like ldapmodify, selects LDAP V3 as the 
preferred protocol by using ldap_init instead of ldap_open. 

-w passzvd I ? 

Use passwd as the password for authentication. Use the ? to generate a 
password prompt. Using this prompt prevents your password from being 
visible through the ps command. 

-z sizelimit 

Limit the results of the search to at most sizelimit entries. This makes it 
possible to place an upper bound on the number of entries that are 
returned for a search Operation. 

-Z Use a secure SSL connection to communicate with the LDAP Server. The -Z 
Option is supported only when the SSL componentry, as provided by the 
GSKit, is installed. 

-9 p Sets criticality for paging to false. The search is handled without paging. 

-9 s Sets criticality for sorting to false. The search is handled without sorting. 

Output format 

If one or more entries are found, each entry is written to Standard output in the 
following form: 
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Distinguished Name (DN) 
attributename=value 
attributename=value 
attributename=value 


Multiple entries are separated with a single blank line. If the -F Option is used to 
specify a Separator character, it is used instead of the equals ( = ) character. If the -t 
Option is used, the name of a temporary file is used in place of the actual value. If 
the -A Option is given, only the attri butename part is written. 

Examples 

The following command: 

Idapsearch "cn=john doe" cn telephoneNumber 

performs a subtree search (using the default search base) for entries with a 
commonName of john doe. The commonName and telephoneNumber values are 
retrieved and printed to Standard output. If two entries are found, the output 
might look something like this: 

cn=John E Doe, ou="College of Literature, Science, and the Arts", 
ou=Students, ou=People, o=University of Higher Learning, c=US 

cn=John Doe 

cn=John Edward Doe 

cn=John E Doe 1 

cn=John E Doe 

telephoneNumber=+l 313 555-5432 


cn=John B Doe, ou=Information Technology Division, 
ou=Faculty and Staff, ou=People, o=University of Higher Learning, c=US 

cn=John Doe 

cn=John B Doe 1 

cn=John B Doe 

telephoneNumber=+l 313 555-1111 
The command 

Idapsearch -t "uid=jed" jpegPhoto audio 

performs a subtree search using the default search base for entries with user ID of 
"jed". The jpegPhoto and audio values are retrieved and written to temporary files. 
The output might look like this if one entry with one value for each of the 
requested attributes is found: 

cn=John E Doe, ou=Information Technology Division, 
ou=Faculty and Staff, 

ou=People, o=University of Higher Learning, c=US 
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audio=/tmp/ldapsearch-audio-a19924 
jpegPhoto=/tmp/ldapsearch-jpegPhoto-al9924 

The command 

Idapsearch -L -s one -b "c=US" "o=university*" o description 

performs a one-level search at the c=US level for all organizations whose 
organizationName begins with university. Search results are displayed in the 
LDIF format (see LDAP Data Interchange Format). The organizationName and 
description attribute values are retrieved and printed to Standard output, resulting 
in output similar to the following: 
dn: o=University of Neptune, c=US 

o: University of Neptune 

description: Preparing Neptune for a brave new tomorrow 
description: leaf node only 

dn: o=University of Saturn at Pluto, c=US 
o: University of Saturn at Pluto 
description: No personnel information 
description: Institution of education and research 

dn: o=University of Saturn at Venus, c=US 
o: University of Saturn at Venus 
o: USV 
o: SU/Venus 
o: SU-Venus 

description: Institute for Higher Learning and Research 

dn: o=University of Jupiter, c=US 
o: University of Jupiter 
o: UJu 

description: Shaper of young minds 


This command: 

Idapsearch -b "c=US" -o ibm-slapdDN "objectclass=person" ibm-slapdDN 
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performs a subtree level search at the c=US level for all persons. This special 
attribute is new in 5.2 and when used for sorted searches, the search results are 
sorted by the string representation of the Distinguished Name (DN). The output 
might look something like this: 

cn=Al Edwards,ou=Widget Division,ou=Austin,o=IBM,c=US 
cn=Al Garcia,ou=Home Entertainment,ou=Austin,o=IBM,c=US 
cn=Amy Nguyen,ou=In Flight Systems,ou=Austin,o=IBM,c=US 
cn=Arthur Edwards,ou=Widget Division,ou=Austin,o=IBM,c=US 
cn=Becky Garcia,ou=In Flight Systems,ou=Austin,o=IBM,c=US 
cn=Ben Catu,ou=In Flight Systems,ou=Austin,o=IBM,c=US 
cn=Ben Garcia Jr,ou=Home Entertainment,ou=Austin,o=IBM,c=US 
cn=Bill Keller Jr.,ou=In Flight Systems,ou=Austin,o=IBM,c=US 
cn=Bob Campbel1,ou=In Flight Systems,ou=Austin,o=IBM,c=US 


Diagnostics 

Exit Status is 0 if no errors occur. Errors result in a nonzero exit Status and a 
diagnostic message being written to Standard error. 


SSL notes 


See "SSL notes" on page 10 


See also 

ldapadd, ldapchangepwd, ldapdelete, ldapexop, ldap_modify ldap_modrdn, 
ldap_ssl_init, ldif, ldap_sort, ldap_parse_results 


IBMDIRCTL 


The administration daemon control program. 

Note: Only the administrator can use this utility. 

Synopsis 

ibmdirctl [-D adminDN] [-h hostname] [-K keyfile] [ -N key_name ] 

[-p port] [-v] [-w adminPW | ?] [-Z] [-?] 
commcmd -- [ibmslapd options] 

where command is {start I stop I restart I status} 

Description 

The administration daemon control program, ibmdirctl, is used to start, stop, 
restart or query the status of the Server. If ibmslapd options are requested, they 
must be preceded by the 

To display syntax help for ibmdirctl, type ibmdirctl -?. 
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Options 


-D adminDN 

Use adminDN to bind to t he LDAP directory. The adminDN should be a 


string-rep resented DN (see | Appendix C, 
page 179}. 


'LDAP distinguished names", on 


-h hostname 

Specify an altemate host on which the LDAP Server and the admin 
daemon are running. 


-K keyfile 

Specifies the file to use for keys. 


-N key_name 

Specifies the private key name to use in keyfile. 


-p port 

Specify an altemate TCP port where the admin daemon is listening. The 
default LDAP port is 3538. 


-v Specifies to run in verbose mode. 

-w adminPW I ? 

Use adminPW as the password for authentication. Use the ? to generate a 
password prompt. Using this prompt prevents your password from being 
visible through the ps command. 


Displays the help screen. 


command 

• Start - Start the Server. 

• stop - Stop the Server. 

• restart - Stop then start the Server. 

• Status - Query the status the Server. 


Note: The stop command can be issued directly to the LDAP Server. 

-- ibmslapd options 

The ibmslapd options are any options the ibmslapd process takes at 
startup time, typically: 

• -a I -A - Start the Server in configuration only mode. 

• -n I -N - Do not start the Server if the Server is unable to start with the 
database backends (no configuration only mode). 

Notes: 

1. If ibmslapd options are requested, they must be preceded by the 

2. The ibmslapd options are ignored if the stop command is issued. 


Example 

To start the Server in configuration only mode issue the command: 
ibmdirctl -h mymachine -D myDN -w mypassword -p 3538 start -- -a 

To stop the Server issue the command: 

ibmdirctl -h mymachine -D myDN -w mypassword -p 3538 stop 
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Chapter 3. API categories 


The following sets of APIs are supported by the IBM Directory Server: 

• |"LDAP_ABANDON" 

• "LDAP_ADD" on page 39 

• "LDAP_BIND / UNBIND" on page 41 

• "LDAP_CODEPAGE" on page 48| 

• "LDAP_COMPARE" on page 56| 

• "LDAP Controls" on page 58 

• "LDAP_CREATE_PROXYAUTH_CONTROL" on page 54 

• "LDAP_DELETE" on page 59 


• |"LDAP_ERROR" on page 61 


"LDAP_EXTENDED_OPERATION" on page 68 

"LDAP_FIRST_ATTRIBUTE" on page 70 



"LDAP_FIRST_ENTRY, LDAP_FIRST_REFERENCE" on page 71 

"LDAP_GET_BIND_CONTROLS" on page 74 



• |"LDAP_GET_DN" on page 75 


• |"LDAP_GET_VALUES" on page 77 


"LDAPJNIT" on page 79 



"LDAP MEMFREE" on page 91 


"LDAP_MESSAGE" on page 92 


"LDAP MODIFY" on page 93 


"LDAP_PAGED_RESULTS" on page 96 


• |"LDAP_PARSE_RESULT" on page 100 


• | // LDAP_PASSWORD_POLICY" on page 102 

• |"LDAP_PLUGIN_REGISTRATION" on page 103 

• |"LDAP_RENAME" on page 106 

• |"LDAP_RESULT" on page 109| 

• |"LDAP_SEARCH" on page 111 

• |"LDAP_SERVER_INFORMATION IN DNS" on page 115 


"LDAP SSL" on page 131 


"LDAP START TLS" on page 13t 

3 

"LDAP STOP TLS" on page 139 


"LDAP_SSL_ENVIRONMENT_INIT" on page 143 

"LDAP SORT" on page 144 



"LDAP URL" on page 140 



LDAP_ABANDON 

ldap_abandon 

ldap_abandon_ext 


Purpose 

Abandon an LDAP Operation in progress. 


© Copyright IBM Corp. 2002 
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Synopsis 

linclude <ldap.h> 


int ldap_abandon( 

LDAP *ld, 

int msgid) 


int ldap_abandon_ext( 
LDAP 
int 

LDAPControl 

LDAPControl 


*ld, 

msgid, 

** S erverctrl s, 
**clientctrls) 


Input Parameters 


ld 


msgid 


Specifies the L D AP pointer re turned by a previous call to ldap_init() 


ldap_ssl_init() or ldap_open() 


The message ID of an outstanding LDAP Op eration, as re turn ed by a call 
to an asynchronous LDAP Operation such as ldap_search and ldap_modify, 
and so forth. 


serverctrls 

Specifies a list of LDAP Server Controls. This parameter can be set to 
NULL. See "LDAP Controls" on page 58 for more Information about Server 
Controls. 

clientctrls 

Spe cifies a list of LDAP dient Co ntrols. This parameter can be set to NULL. 
See "LDAP Controls" on page 58 for more information about dient Controls. 


Usage 

The ldap_abandon() and ldap_abandon_ext() APIs are used to abandon or cancel 
an LDAP Operation in progress. The msgid passed must be the message ID of an 
outstanding LDAP Operation, as returned by a call to an asynchronous LDAP 
Operation such as ldap_search(), ldap_modify(), and so forth. 

Both APIs check to see if the result of the Operation has already been returned by 
the Server. If the result of the Operation has been returned, both APIs delete the 
result of the Operation from the queue of pending messages. If not, both APIs send 
an LDAP abandon Operation to the LDAP Server. 

The result of an abandoned Operation is not returned from a future call to 
ldap_result(). 

The ldap_abandon() API returns 0 if the abandon was successful or -1 if 
unsuccessful; it does not support LDAP V3 Server Controls or dient Controls. The 
ldap_abandon_ext() API returns the constant LDAP_SUCCESS if the abandon was 
successful, or another LDAP error code if not. 


Errors 


ldap_abandon() returns 0 i f the Operation is successful, - 1 if unsuccessful. 


ld_ermo appropriately. See "LDAP_ERROR" on page 61 


for details. 


ldap_abandon_ext() returns LDAP_SUCCESS if successful and returns an 
error code if unsuccessful. 


setting 

LDAP 
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See also 


ldap_result ldap_error 


LDAP ADD 


ldap_add 

ldap_add_s 

ldap_add_ext 

ldap_add_ext_s 


Purpose 

Perform an LDAP Operation to add an entry. 

Synopsis 

#include <ldap.h> 


int ldap_add( 

LDAP *ld, 

const char *dn, 

LDAPMod *attrs[]) 

int ldap_add_s( 

LDAP *ld, 

const char *dn, 

LDAPMod *attrs[]) 


int ldap_add_ext( 
LDAP 

const char 
LDAPMod 
LDAPControl 
LDAPControl 
i nt 


*ld, 

*dn, 

*attrs[], 
**serverctrls, 
**clientctrls, 
*msgidp) 


int 1dap_add_ext_s( 
LDAP 

const char 
LDAPMod 
LDAPControl 
LDAPControl 


*1 d, 

*dn, 

*attrs[], 
**serverctrls, 
**clientctrls) 


Input Parameters 


ld 


Specifies the L D AP Pointer re turned by a previous call to ldap_init() 


ldap_ssl_init() or ldap_open() 


dn The DN of the entry to add. 

attrs Th e entry's attribu tes, specified using the LDAPMod structure, as defined 
for ldap_modify() The mod_type and mod_vals fields must be filled in. 
The mod_op field is ignored unless ORed with the constant 
LDAP_MOD_BVALUES. In this case, the mod_op field is used to select the 
modjbvalues case of the mod_vals union. 


serverctrls 

Specifies a list of LDAP Server Controls. This parameter can be set to 


NULL. See 
Controls. 


'LDAP Controls" on page 58 


for more information about Server 
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clientctrls 

Spe cifies a list of LDAP dient Co ntrols. This parameter can be set to NULL. 


See "LDAP Controls" on page 58 for more Information about dient Controls. 


Output Parameters 

msgidp 

This result parameter is set to the message ID of the request if the 
ldap_add_ext() call succeeds. 


Usage 


The ldap_add() and associated APIs are used to perform an LDAP add Operation. 
They take dn, the DN of the entry to add, and attrs, a NULL- terminated arra y of 


the entry's attributes. The LDAPMod structure (as defined for ldap_modify() 


is 


used to represent attributes, with the mod type and mod_values fields being filled 
in and used as described for ldap_modify(). The mod_op field is ignored unless 
ORed with the constant LDAP_MOD_BVALUES. In this case, the mod_op field is 
used to select the modjbvalues case of the mod_vals union. 

Note: All entries except those specified by the last component in the given DN 
must already exist. 

The ldap_add_ext() API initiates an asynchronous add Operation and returns the 
constant LDAP_SUCCESS if the request was successfully sent, or another LDAP 
error code if not. If successful, l dap_add_ext() places the message ID of the request 
in *msgidp. A subsequent call to ldap_result() can be used to obtain the result of 
the Operation. After the Operation has completed, ldap_result() returns a result that 
contains the Status of the Operation (in the form of an error code). The error cod e 


indicates whether the Operation completed successfully. The |ldap_parse_result() 
API is used to check the error code in the result. 


Similarly, the ldap_add() API initiates an asynchronous add Operation and returns 
the message ID of the Operation initiated. A subsequent call to ldap_result(), can be 
used to obtain the result of the add. In case of error, ldap_add() returns -1, setting 
the session error P arameters in the L DAP structure appropriately, which can be 


obtained by using |ldap_get_errno() 


See |"LDAP_ERROR" on page 61| for more details. 


The ldap_add_ext() and ldap_add_ext_s() APIs both support LDAP V3 Server 
Controls and dient Controls. 


Errors 

ldap_add() returns -1 in case of error initiating the request. ldap_add_s() and 
ldap_add_ext_s() returns an LDAP error code directly; LDAP_SUCCESS if the call 
was successful, an LDAP error if the call was unsuccessful. 

See also_ 

ldap_modify 
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LDAP_BIND / UNBIND 

ldap_sasl_bind 

ldap_sasl_bind_s 

ldap_simple_bind 

ldap_simple_bind_s 

ldap_unbind 

ldap_unbind_ext 

ldap_unbind_s 

ldap_set_rebind_proc 

ldap_bind (deprecated) 

ldap_bind_s (deprecated) 


Purpose 

LDAP routines for binding and unbinding. 

Synopsis 


finclude <ldap.h> 


int 

ldap sasl bind( 



LDAP 

*ld, 


const char 

*dn. 


const char 

*mechanism, 


const struct berval *cred. 


LDAPControl 

**servctrls. 


LDAPControl 

**clientctrls. 


int 

*msgidp) 

i nt 

ldap sasl bind s( 



LDAP 

*ld. 


const char 

*dn. 


const char 

*mechanism, 


const struct berval *cred. 


LDAPControl 

**servctrls. 


LDAPControl 

**clientctrls. 


struct berval 

**servercredp) 

i nt 

ldap simple bind( 



LDAP 

*ld, 


const char 

*dn. 


const char 

*passwd) 


i nt 

ldap simple bind 

s( 


LDAP 

*ld, 


const char 

*dn. 


const char 

*passwd) 

int 

ldap unbind( 



LDAP 

*1 d) 

i nt 

ldap unbind s( 



LDAP 

*1 d) 

int 

ldap unbind ext( 



LDAP 

*ld, 


LDAPControl 

**servctrls. 


LDAPControl 

**cl ientctrl 
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void ldap_set_rebind_proc( 

LDAP *ld, 

LDAPRebindProc rebindproc) 


int ldap_bind( 

LDAP *ld, 

const char *dn, 

const char *cred, 

int method) 


int ldap_bind_s( 

LDAP *ld, 

const char *dn, 

const char *cred, 

int method) 


Input Parameters 

ld Specifies the L D AP pointer re turned by a previous call to ldap_init() 


ldap_ssl_init()| or |ldap_open() 


dn Specifies the |Distinguished Name| ( DN) of the entry to bind as. 


mechanism 

Although a variety of mechanisms have been IANA (Internet Assigned 
Numbers Authority) registered, the only native mechanisms supported by 
the LDAP library at this time are: 

• LDAP_MECHANISM_EXTERNAL mechanism, represented by the string 
EXTERNAL. 

• LDAP_MECHANISM_CRAMMD5 mechanism, represented by the string 
CRAM-MD5. 

• LDAP_MECHANISM_GSSAPI mechanism, represented by the string 
GSSAPI. 

• LDAP_MECHANISM_DIGEST_MD5 mechanism, represented by the 
string DIGEST-MD5. 


The LDAP_MECHANISM_EXTERNAL mechanism indicates to the Server 
that Information external to SASL must be used to determine whether the 
dient is authorized to authenticate. For this implementation, the System 
providing the external information must be SSL. For example, if the dient 
sets the DN and credentials to NULL (the value of the pointers must be 
NULL), with mechanism set to LDAP_MECHANISM_EXTERNAL, the 
dient is requesting that the Server use the strongly authenticated identity 
from the client's X.509 certificate that was used to authenticate the dient to 
the Server during the SSL handshake. The Server can then use the strongly 
authenticated identity to access the directory. 


The LDAP_MECHANISM_CRAMMD5 mechanism is used to authenticate 
your ID and password with the Server using a challenge/response protocol 
that protects the clear-text password over the wire. This mechanism is 
useful only when the LDAP Server can retrieve the user's password. If the 
password is stored in a hashed form, for example, crypt or SHA, then 
authentication using the cram-md5 mechanism fails. 


The LDAP_MECHANISM_GSSAPI mechanism is used to enable Kerberos 
authentication. In Kerberos authentication, a dient presents valid 
credentials obtained from a Kerberos key distribution center (KDC) to an 
application Server. The Server decrypts and verifies the credentials using its 
Service key. 
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When mechanism is set to a NULL pointer, the SASL bind request is 
interpreted as a request for simple authentication, that is, equivalent to 
using ldap_simple_bind() or ldap_simple_bind_s(). 


See 

"LDAP PLUGIN REGISTRATION" on page 103 

for more information 

about using LDAP client plue-ins. See 

Chapter 6, "LDAP client plug-in 


programming reference", on page 163 

for more information about 



developing an LDAP client plug-in. 


The LDAP_MECHANISM_DIGEST_MD5 mechanism is used to 
authenticate your ID and password with the Server using a 
challenge/response protocol that protects the clear-text password over the 
wire and prevents replay attacks. 

This mechanism is useful only when the LDAP Server can retrieve the 
user's password. If the password is stored in a hashed form, for example, 
crypt or SHA, then authentication using the DIGEST-MD5 mechanism fails. 
When using the DIGEST-MD5 mechanism, the hostname supplied on the 
ldap_init call must resolve to the fully qualified hostname of the Server. 


The application must supply a username on the ldap_sasl_bind_s call by 
using the IBM_CLIENT_MD5_USER_NAME_OID client control. The 
application can optionally supply a realm on the ldap_sasl_bind_s call by 
using the IBM_CLIENT_MD5_REALM_NAME_OID client control. The 
application can optionally supply an authorization ID as the dn parameter. 

cred Specifies the credentials with which to authenticate. Arbitrary credentials 
can be passed using this parameter. In most cases, this is the user's 
password. When using a Simple Authentication Security Layer (SASL) 
bind, the format and content of the credentials depends on the setting of 
the mechanism parameter. 

method 

Selects the authentication method to use. Specify LDAP_AUTH_SIMPLE 
for simple authentication or LDAP_AUTH_SASL for SASL bind. Note that 
use of the ldap_bind and ldap_bind_s APIs is deprecated. 

passwd 

Specifies the password used in association with the DN of the entry in 
which to bind. 


serverctrls 


Specifies a list of LDAP Server Controls. See "LDAP Controls" on page 58 
for more information about Server Controls. 


clientctrls 

Specifies a list of LDAP client Controls. See 
more information about client Controls. 


'LDAP Controls" on page 58 for 


rebindproc 

Specifies the entry-point of a routine that is called to obtain bind 
credentials used when a new Server is contacted following an LDAP 
referral. 


Output Parameters 

msgidp 


This result parameter is set to the message ID of the request if the 
ldap_sasl_bind() call succeeds. 


Chapter 3. API categories 43 










servercredp 

This result parameter is set to the credentials returned by the Server. If no 
credentials are returned, it is set to NULL. 


Usage 

These routines provide various interfaces to the LDAP bind Operation. After using 
ldap_init, ldap_ssl_init or ldap_open to create an LDAP handle, a bind can be 
performed before other operations are attempted over the Connection. Both 
synchronous and asynchronous versions of each variant of the bind call are 
provided. 

A bind is optional when communicating with an LDAP Server that Supports the 
LDAP V3 protocol. The absence of a bind is interpreted by the LDAP V3 Server as 
a request for unauthenticated access. A bind is required by LDAP Servers that only 
support the LDAP V2 protocol. 

The ldap_simple_bind() and ldap_simple_bind_s() APIs provide simple 
authentication, using a user ID or dn and a password passed in clear-text to the 
LDAP API. 


The ldap_bind() and ldap_bind_s() provide general authentication routines, where 
an authentication method can be chosen. In this toolkit, method must be set to 
LDAP_AUTH_SIMPLE. Because the use of these two APIs is deprecated, 
ldap_simple_bind and ldap_simple_bind_s must be used instead. 

The ldap_sasl_bmd and ldap_sasl_bind_s APIs can be used to do general and 
extensible authentication over LDAP through the use of the SASL. 


All bind routines take ld as their first parameter as returned from ldap_init, 
ldap_ssl_init, or ldap_open. 


Simple authentication 

The simplest form of the bind call is ldap_simple_bmd_s(). It takes the DN to bind 
and the user's password (supplie d in passwd). It retums an LDAP error indication 


(see |"LDAP_ERROR" on page 61|). The ldap_simple_bind() call is asynchronous. 


taking the same parameters but only initiating the bind Operation and returning 
the message ID of the re quest it sent. T he result of the Operation can be obtained 
with a subsequent call to |ldap_result() 


General authentication 

The ldap_bind() and ldap_bind_s() routines are deprecated. 


The deprecated APIs can be used when the authentication method is selected at 
runtime. They both take an extra method parameter when selecting the 
authentication method to use. However, when using this toolkit, method must be 
set to LDAP_AUTH_SIMPLE, to select simple authentication. ldap_bind() and 
ldap_simple_bind() return the message ID of the initiated request. ldap_bind_s() 
and ldap_simple_bind_s() return an LDAP error indication on unsuccessful 
completion, or LDAP_SUCCESS on successful completion. 

SASL authentication 

Five categories of SASL authentication are supported: 

• SASL authentication using the EXTERN AL mechanism 

• SASL authentication using the GSSAPI mechanism (Kerberos is supported and 
implemented as a plug-in) 
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• SASL authentication using the cram-md5 mechanism (implemented as a plug-in) 

• SASL authentication using a user-supplied SASL plug-in library 

• SASL authentication using a SASL mechanism implemented by the application 
itself 

When the input parameter mechanism is set to a NULL pointer, the SASL bind 
request is interpreted as a request for simple authentication, that is, equivalent to 
using ldap_simple_bind() or ldap_simple_bind_s(). 


Also note that the SASL authentication mechanism provides a facility for the LDAP 
Server to retum Server credentials to the dient. An application can obtain the 
Server credentials returned fro m the Server in the SASL bind result with the 
ldap_parse_sasl_bind_result() API. 


EXTERNAL SASL binds: The primary reason for using the EXTERNAL SASL 
bind mechanism is to use the dient authentication mechanism provided by SSL to 
strongly authenticate to the directory Server using the client's X.509 certificate. For 
example, the dient application can use the following logic: 

• ldap_ssl_client_init (initialize the SSL library) 

• ldap_ssl_init (host, port, name), where name references a public/private key pair 
in the client's key database file 

• ldap_sasl_bind_s (ld, dn=NULL, mechanism=LDAP_MECHANISM_EXTERNAL, 
cred=NULL) 

A Server that supports this mechanism, such as the IBM Directory Server, can then 
access the directory using the strongly authenticated dient identity as extracted 
from the client's X.509 certificate. 


GSSAPI SASL binds: Kerberos authentication is supported in this release. If the 
input parameters for ldap_sasl_bind or ldap_sasl_bind_s are mechanism==GSSAPI 
and cred==NULL, then it is assumed that the user has already authenticated to a 
Kerberos security Server and has obtained a ticket granting ticket (TGT), either 
through a desktop log-on process, or by using a program such as kinit. The 
GSSAPI credential handle used to initiate a security context on the LDAP dient 
side is obtained from the current login context. If the input parameters for these 
two SASL bind functions are mechanism==GSSAPI and cred!=NULL, the caller of 
the functions must provide the GSSAPI credential handle for the LDAP dient to 
initiate a security context with an LDAP Server. For example, an LDAP Server can 
call a SASL bind function with a credential handle that the Server received from a 
dient as a delegated credential handle. 

CRAM-MD5 SASL binds: The cram-md5 SASL mechanism is used to hide the 
credentials on the wire. The cram-md5 plug-in supplied with the IBM Directory 
Server C-Client SDK implements a multi-bind challenge with the LDAP Server. If 
the multi-bind challenge is successful, the dient is authenticated to the Server 
without actually flowing the credentials, for example, a password, in the clear on 
the wire. 


Note: The cram-md5 mechanism is implemented as a SASL bind plug-in. SASL 
bind plug-ins are only accessible using the synchronous ldap_sasl_bind_s() 
API. The asynchronous ldap_sasl_bind() API is not supported for use with 
SASL plug-ins. 
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See "LDAP_PLUGIN_REGISTRATION " on page 103 for more information about 


using an LDAP dient p lug-in. See Chapter 6, "LDAP dient plug-in programming 


reference", on page 163 for more Information about developing an LDAP dient 
plug-in. 


DIGEST-MD5 SASL binds: The Server accepts SASL bind requests using the 
DIGEST-MD5 mechanism. There are two types of DIGEST-MD5 bind requests: 
Initial Authentication bind requests and Subsequent Authentication bind requests. 
Initial Authentication is required and and supported by IBM Tivoli Directory 
Server. Subsequent Authentication support is optional, and is not supported by 
IBM Tivoli Directory Server. 


The Server responds to a DIGEST-MD5 SASL bind request with a digest-challenge. 
The challenge contains the values required by RFC2831 section 2.1.1, with the 
following implementation-specific behavior: 

• realm - The Server always sends the realm that the Server is configured to be in. 

• nonce - The Server generates a random nonce. 

• qop-options - The Server supports "auth" only. 


The next response from the dient to the Server must be another DIGEST-MD5 

SASL bind message. The response includes several fields containing values that the 

Server uses as follows: 

• username - The Server uses the the username value to determine whether the 
user is binding as an administrator or to find an entry in the primary rdbm 
backend. If the username is an administrator's DigestUsemame, then the Server 
uses that administrator to bind. If the username was not an administrator's, then 
the Server searches the primary rdbm for a user with that username. If the 
username doesn't correspond to a single entry or the entry doesn't have a 
userpassword value, the Server returns LDAP_INVALID_CREDENTIALS. It will 
also print out the appropriate error message. 

• realm - The value in the realm field must match the realm that the Server is 
configured to be in. If the realm value does not match the realm that the Server 
is configured to be in, the Server returns LDAP_PROTOCOL_ERROR. 

• nonce - The value in the nonce field must match the nonce value that the Server 
sent the dient with the digest-challenge. If the value does not match, the Server 
returns LDAP_PROTOCOL_ERROR. 

• response - The value in the response field contains a hash of the password. For 
each of the userpassword values that the Server can get from the user entry, it 
generates the DIGEST-MD5 hash and compares it with the hash sent by the 
dient. If one matches, the Server returns LDAP_SUCCESS and the user is bound 
as that user. Otherwise, the Server returns LDAP_INVALID_CREDENTIALS and 
prints out an error message. 

• authzid - The value in the authzid field can contain a "dn:"- or "u: "-style 
authorization ID from RFC 2829 that the Server will use for authority checking 
after the bind, rather than the entry found for the username, similar to Proxied 
Authentication. The entry that the username corresponds to needs to have the 
authority to use the other DN. If the authzid contains a "u: "-style authorization 
ID, the Server maps the value to an entry the same as was done for the 
username parameter. If the mapping fails the Server returns 
LDAP_INVALID_CREDENTIALS. 


User-supplied SASL plug-ins: The application developer, or a third party, can 
implement additional SASL mechanisms using the IBM Directory Server C-Client 
SASL plug-in facility. For example, a dient and Server SASL plug-in can be 
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developed that Supports a new authentication mechanism based upon a retinal 
scan. If the mechanism associated with this new authentication mechanism is 
retscan, the application simply invokes ldap_sasl_bind() with mechanism set to 
retscan. Depending on how the mechanism and plug-in are designed, the 
application might be required to also supply the user's DN and credentials. 
Altematively, the plug-in itself might be responsible for obtaining the user's 
identity and credentials, which are derived in some way from a retinal scan image. 


If the retinal scan plug-in is not defined in ibmldap.conf, the applicatio n must 


explicitly regist er the plug-in, using the ldap_register_plugin() API. See "Defining a 


SASL plug-in" f or information about defining a SASL plug-in for use with an 


application. See 

"LDAP PLUGIN REGISTRATION" on page 103 

for more 

information about usine an LDAP dient plue-in. See 

Chapter 6, "LDAP dient 


plug-in programming reference", on page 163 


developing an LDAP dient plug-in. 


for more information about 


SASL mechanisms implemented by the application: In some cases, the SASL 
mechanism might not require the presence of a plug-in, or any special support in 
the LDAP library. If the application can invoke the ldap_sasl_bind() or 
ldap_sasl_bind_s() API with the parameters appropriate to the mechanism, the 
LDAP library simply encodes the SASL bind request and sends it to the Server. If a 
plug-in is defined for the specified mechanism, the request is diverted to the 
plug-in, which can perform additional processing betöre sending the SASL bind to 
the Server. 


SASL mechanisms supported by the LDAP Server: The application can query the 
LDAP server's root DSE, using ldap_search() with the following settings: 

• base DN set to NULL 

• scope set to base 

• filter set to "(objectclass=*)" 

If the LDAP Server supports one or more SASL mechanisms, the search results 
include one or more values for the supportedsaslmechanisms attribute type. 


Defining a SASL plug-in: When the application issues an ldap_sasl_bind_s() API 
with a mechanism that is supported by a particular SASL plug-in, the LDAP 
library must be able to locate the plug-in shared library. Two mechanisms are 
available for making an LDAP dient plug-in known to the LDAP library: 

• The plug-in for the specified SASL mechanism is defined in the ibmldap.conf 
file. By default, the IBM Directory Server C-Client cram-md5 plug-in is defined 
in ibmldap.conf. 


The plug-in has been e xplicitly registered by the application, using the 


ldap_register_plugin() 


API. 


See "Finding the Plug-in library" on page 105 for more information about locating 


a plug-in library and defining plug-ins in the ibmldap.conf file. 


Unbinding 

ldap_unbind_ext(), ldap_unbind(), and ldap_unbind_s() are synchronous APIs, in 
the sense that they send an unbind request to the Server, close all open connections 
associated with the LDAP session handle, and dispose of all resources associated 
with the session handle betöre returning. Note that there is no Server response to 
an LDAP unbind Operation. All three of the unbind functions return 
LDAP_SUCCESS or another LDAP error code if the request cannot be sent to the 
LDAP Server. After a call to one of the unbind functions, the session handle ld is 
invalid and it is illegal to make any further LDAP API calls using the ld. 
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The ldap_imbind() and ldap_unbind_s() APIs behave identically. The 
ldap_imbind_ext() API allows Server and client Controls to be included explicitly, 
but note that because there is no Server response to an unbind request there is no 
way to receive a response to a Server control sent with an unbind request. 

Re-binding while following referrals 

The ldap_set_rebind_proc() call is used to set the entry-point of a routine that is 
called back to obtain bind credentials for use when a new Server is contacted 
following an LDAP referral or search reference. Note that this function is available 
only when LDAP_OPT_REFERRALS is set. This is the default setting. If 
ldap_set_rebind_proc() is never called, or if it is called with a NULL rebindproc 
parameter, an unauthenticated simple LDAP bind is always done when chasing 
referrals. The SSL characteristics of the connections to the referred to Servers are 
preserved when chasing referrals. In addition, if the original bind was an LDAP V3 
bind, an LDAP V3 bind is used to connect to the referred-to Servers. If the original 
bind was an LDAP V2 bind, an LDAP V2 bind is used to connect to each 
referred-to Server. 

rebindproc must be a function that is declared like the following: 
int rebindproc! LDAP *ld, char **whop, char **credp, 

int *methodp, int freeit ); 


The LDAP library first calls the rebindproc to obtain the referral bind credentials, 
and the freeit parameter is zero. The whop, credp, and methodp parameters must 
be set as appropriate. If the rebindproc returns LDAP_SUCCESS, referral 
Processing continues, and the rebindproc is called a second time with freeit 
nonzero to give the application a chance to free any memory allocated in the 
previous call. 

If anything other than LDAP_SUCCESS is returned by the first call to the 
rebindproc, referral processing is stopped and the error code is returned for the 
original LDAP Operation. 


Errors 


Asynchronous ro utines return -1 in case of error. To obtain the LDAP error, use the 


ldap_get_errno() API. Synchronous routines return the LDAP error code resulting 


from the Operation. 


See also 


LDAP_GET_BIND_CONTROLS ldap_error ldap_open 


LDAP_CODEPAGE 

ldap_xlate_local_to_utf8 

ldap_xlate_utf8_to_local 

ldap_xlate_local_to_unicode 

ldap_xlate_unicode_to_local 

ldap_set_locale 

ldap_get_locale 

ldap_set_iconv_local_codepage 

ldap_get_iconv_locale_codepage 

ldap_set_iconv_local_charset 
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ldap_char_size 


Purpose 

Functions for managing the conversion of strings between UTF-8 and a local code 
page. 

Synopsis 

linclude <ldap.h> 


int 

1dap_xlate_ 

_1 ocal 

_to_utf8( 


char 


*inbufp. 


unsigned 

1 ong 

*inlenp. 


char 


*outbufp, 


unsigned 

1 ong 

*outlenp) 

i nt 

1dap_xlate_ 

_utf8_ 

to_local( 


char 


*inbufp. 


unsigned 

1 ong 

*inlenp. 


char 


*outbufp. 


unsigned 

1 ong 

*outlenp) 

i nt 

1dap_xlate_ 

1 ocal 

_to_unicode( 


char 


*inbufp. 


unsigned 

1 ong 

*inlenp. 


char 


*outbufp, 


unsigned 

1 ong 

*outlenp) 

int 

1dap_xlate_ 

Unicode to 1ocal( 


char 


*inbufp. 


unsigned 

1 ong 

*inlenp. 


char 


*outbufp, 


unsigned 

1 ong 

*outlenp) 

int 

ldap set localef 



char 


*1 ocale) 


char *ldap_get_locale( ) 

int 1dap_set_iconv_local_codepage 
char *codepage) 

char *ldap_get_iconv_local_codepage( ) 

int 1dap_set_iconv_local_charset( 
char *charset) 

int ldap_char_size( 

char *p) 

Input Parameters 

inbufp 

A pointer to the address of the input buffer containing the data to be 
translated 

inlenp Length in bytes of the inbufp input buffer 

outbufp 

A pointer to the address of the output buffer for translated data 

outlenp 

Length in bytes of the outbufp input buffer 
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charset 


Note: The output buffer must be three times as large as the input buffer if 
the intent is to translate the entire input buffer in a single call. 


Specifies the character set to be use d when converting strings between 


TANA character sets supported by 


UTF-8 and the local co de page. See 
platform" on page 184 for the specific charset values that are supported for 
each operating System platform. 


Note: The supported values for charset are the same values supported for 
the charset tag that is optionally defined in Version 1 LDIF files. 

codepage 

Specifies a code page or code set for overriding the active code page for 
the currently defined locale. See the System documentation for the code 
pages supported for a particular operating System. 

locale Specifies the locale to be used by LDAP when converting to and from 

UTF-8 or Unicode. If the locale is not explicitly set, the LDAP library uses 
the application's default locale. To force the LDAP library to use another 
locale, specify the appropriate locale string. 

For applications running on the Windows platform, supported locales are 
defined in ldaplocale.h. For example, the following is an excerpt from 
ldaplocale.h and shows the available French locales: 

/* French - France */ 

Idefine LDAP_L0CALE_FRFR850 "Fr_FR" 

Idefine LDAP LOCALE FRFRIS08859 1 "fr FR" 


For applications running on the AIX operating System, see the locale 
definitions defined in the "Understanding Locale" chapter of AIX System 
Management Guide: Operating System and Devices. System-defined locales are 
located in /usr/lib/nls/loc on the AIX operating System. For example, 
Fr_FR and fr_FR are two system-supported French locales. 

For Solaris applications, see the System documentation for the set of 
system-supported locale definitions. 

Note: The specified locale is applicable to all conversions by the LDAP 

library within the applications address space. The LDAP locale is set 
or changed only when there is no other LDAP activity occurring 
within the application on other threads. 

p Returns the number of bytes constituting the character pointed to by p. For 
ASCII characters, this is 1. For other character sets, it can be greater than 1. 

Output Parameters 

inbufp 

A pointer to the address of the input buffer containing the data to be 
translated 

inlenp Length in bytes of the inbufp input buffer 

outbufp 

A pointer to the address of the output buffer for translated data 

outlenp 

Length in bytes of the outbufp input buffer 
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Usage 


Note: The output buffer must be three times as large as the input buffer if 
the intent is to translate the entire input buffer in a single call. 

locale When retumed from the ldap_get_locale() API, locale specifies the 

currently active locale for LDAP. See the System documentation for the 
locales supported for a particular operating System. For applications 
rurming in the Windows environment, see ldaplocale.h. 

codepage 

When retumed from ldap_get_iconv_local_codepage() API, codepage 
specifies the currently active code page, as associated with the currently 
active locale. See the System documentation for the code pages supported 
for a particular operating System. 


These routines described in the sections below are used to manage 
application-level conversion of data between the local code page and UTF-8, which 
is used by LDAP when communicating with an LDAP V3 compliant Server. For 


more information on the UTF-8 Standard, see "UTF-8, a Transformation Format of 


ISO 10646" 


When connected to an LDAP V3 Server, the LDAP APIs are designed to accept and 
return string data UTF-8 encoded. This is the default mode of Operation. 
Alternatively, your application can rely on t he LDAP library t o convert LDAP V3 
string data to and from UTF-8 by using the ldap_set_option() API to set the 
LDAP_OPT_UTF8_IO Option to LDAP_UTF8_XLATE_ON. Once set, the following 
connection-based APIs, that is, those that accept an ld as input, expect string data 
to be supplied as input in the local code page, and return string data to the 
application in the local code page. In other words, the following LDAP routines 
and related APIs automatically convert string data to and from the UTF-8 wire 
protocol: 


• ldap_add (and family) 

• ldapjbind (and family) 

• ldap_compare (and family) 

• ldap_delete (and family) 

• ldap_parse_reference 

• ldap_get_dn 

• ldap_get_values 

• ldap_modify (and family) 

• ldap_parse_result 

• ldap_rename (and family) 

• ldap_search (and family) 

• ldap_url_search (and family) 


The following APIs are not associated with a connection, and always expect string 
data, for example, DNs, to be supplied and returned UTF-8 encoded: 

• ldap_explode_dn 

• ldap_explode_dns 

• ldap_explode_rdn 

• ldap_server_locate 

• ldap_server_conf_save 

• ldap_is_ldap_url 
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• ldap_url_parse 

• ldap_default_dn_set 

The APIs described in this section provide assistance in Converting your 
application data to and from the locale code page. There are several reasons for 
using these APIs: 

• The application is using one or more of the non-connection oriented APIs, and 
needs to convert strings to UTF-8 from the local code page before using the 
APIs. 

• The application is designed to send and receive strings as UTF-8 when using the 
LDAP APIs, but needs to convert selected strings to the local code page before 
presenting to the user. When the directory contains heterogeneous data, that is, 
data is obtained from multiple countries, or locales, this might be the desired 
approach. 

If your application might be extracting string data from the directory that has 
originated from other countries or locales, design the application with the 
following considerations in mind: 

• Consider Splitting your application into a presentation component, and an LDAP 
worker component. 

- The presentation component is responsible for obtaining data from external 
sources, for example, graphical user interfaces (GUIs), command-lines, files, 
and so forth, as well as displaying the data to a GUI, Standard out, files, and 
so forth. This component typically deals with string data that is represented 
in the local code page. 

- The LDAP worker component is responsible for interfacing directly with the 
LDAP programming interfaces. The LDAP worker component can be 
implemented to deal strictly in UTF-8 when handling string data. The default 
mode of Operation for the LDAP library is to handle strings encoded as 
UTF-8. 

- String conversion between UTF-8 and the local code page occurs when data is 
passed to and from the presentation component and the LDAP worker 
component. 

Consider the following scenario: 

The LDAP worker component issues an LDAP search, and retums a list of 
entries from the directory. To ensure that no data is lost, the default mode is 
used and the LDAP library does not convert string data. In this case, this means 
the DNs of the entries returned from the search are represented in UTF-8. 

The application needs to display this list of DNs on a panel, so the user can 
select the desired entry, and the application then retrieves additional attributes 
for the selected DN. Since the DN is represented in UTF-8, it must be converted 
to the local code page prior to display. 

The converted DN might not be a faithful representation of the UTF-8 DN. For 
example, if the DN was created in China, it can contain Chinese characters. If 
the application is running in a French locale, certain Chinese characters might 
not be converted correctly, and are replaced with a replacement character. 

The application can display the converted DN, but certain characters might be 
displayed as bobs. Assuming there is enough information for the end-user to 
select the desired DN, the application accesses the LDAP directory with the 
selected DN to get additional information, for example, a jpeg image so it can 
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display the user's photograph. Since jpeg images might be large, the application 
is designed to obtain the jpeg attribute after the user selects the specific DN 
only. 


In order to ensure that the search to get the jpeg attribute using the selected DN 
works, the search must be done with the original UTF-8 version of the selected 
DN, not the version of the DN that was converted to the local code page. This 
implies that the application maintains a correlation between the original UTF-8 
version of the DN, and the version that was converted to the local code page. 


If the application is designed to accept user input, generate one or more LDAP 
searches, then display the Information without passing the results back into the 
LDAP library. The application can be designed to let the LDAP library perform 
the conversions, even though some data loss might theoretically occur. 
Automatic conver sion of string data for a specific ld can be enabled by using 


ldap_set_option() with the LDAP_OPT_UTF8_IO Option set to 
LDAP UTF8 XLATE ON. 


ldap_char_size returns the number of bytes constituting the character pointed to by 
p. For ASCII characters, this is 1. For other character sets, it can be greater than 1. 

Translate local code page to UTF-8 

The ldap_xlate_local_to_utf8() API is used to convert a string from the local code 
page to a UTF-8 encoding. Since the output string from the conversion process can 
be larger than the input string, it is strongly recommended that the output buffer 
be at least twice as large as the input buffer. LDAP_SUCCESS is returned if the 
conversion is successful. 

Translate UTF-8 to local code page 

The ldap_xlate_utf8_to_local() API is used to convert a UTF-8 encoded string to the 
local code page encoding. Since the output string from the conversion process can 
be larger than the input string, it is strongly recommended that the output buffer 
be at least twice as large as the input buffer. LDAP_SUCCESS is returned if the 
conversion is successful. 


Note: Translation of strings from a UTF-8 encoding to local code page can result in 
loss of data when one or more characters in the UTF-8 encoding cannot be 
represented in the local code page. When this occurs, a Substitution 
character replaces any UTF-8 characters that cannot be converted to the local 
code page. 

Translate local code page to Unicode 

The ldap_xlate_local_to_unicode() API is used to convert a string from the local 
code page to the UCS-2 encoding as defined by ISO/IEC 10646-1. This same set of 
characters is also defined in the UNICODE Standard. Since the output string from 
the conversion process can be larger than the input string, it is strongly 
recommended that the output buffer be at least twice as large as the input buffer. 
LDAP_SUCCESS is returned if the conversion is successful. 

Translate Unicode to local code page 

The ldap_xlate_unicode_to_local() API is used to convert a UCS-2-encoded string 
to the local code page encoding. Since the output string from the conversion 
process can be larger than the input string, it is strongly recommended that the 
output buffer be at least twice as large as the input buffer. LDAP_SUCCESS is 
returned if the conversion is successful. 

Note: Translation of strings from a UCS-2 (UNICODE) encoding to local code page 
can result in loss of data when one or more characters in the UCS-2 
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encoding cannot be represented in the local code page. When this occurs, a 
Substitution character replaces any UCS-2 characters that cannot be 
converted to the local code page. 

Set locale 

The ldap_set_locale() API is used to change the locale used by LDAP for 
conversions between the local code page and UTF-8 (or Unicode). Unless explicitly 
set with the ldap_set_locale() API, LDAP uses the application's default locale. To 
force the LDAP library to use another locale, specify the appropriate locale string. 
For UNIX Systems, see the System documentation for the locale definitions. For 
Windows operating Systems, see ldaplocale.h. 

Get locale 

The ldap_get_locale() API is used to obtain the active LDAP locale. Values that can 
be returned are system-specific. 

Set codepage 

The ldap_set_iconv_local_codepage() API is used to override the code page 
associated with the active locale. See the System documentation for the code pages 
supported for a particular operating System. 


Get codepage 

The ldap_get_iconv_local_codepage() API is used to obtain the code page 
associated with the active locale. See the System documentation for the code page s 


supported for a particular operating System. SccpTANA character sets supported 


by platform" on page 184| for the specific charset values that are supported for each 
operating System platform. Note that the supported values for charset are the same 
values supported for the charset tag that is optionally defined in Version 1 LDIF 
files. 


Japanese and Korean currency considerations 

The generally accepted convention for converting the backslash character ( \ ) 
(single byte X'5C') from the Japanese or Korean locale into Unicode is to convert 
X'5C' to the Unicode yen for Japanese, or the Unicode won for Korean. 


To change the default behavior, set the LDAP_BACKSLASH environment variable 
to YES prior to using any of the LDAP APIs. When LDAP_BACKSLASH is set to 
YES, the X'5C' character is converted to the Unicode ( \ ) , instead of the Japanese 
yen or Korean won. 


Errors 


Each of the LDAP user configuration APIs return s a nonzero LDAP return code if 
an error occurs. See "LDAP_ERROR" on page 61 for more details. 


See also_ 

ldap_error 


LDAP CREATE PROXYAUTH CONTROL 


ldap_create_proxyauth_control 


Purpose 

Creates an LDAP control that will allow a bind entity to assume a proxy identity. 
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Synopsis 

#include <ldap.h> 


int 1dap_create_proxyauth_control( 
LDAP *ld, 

char *proxyDN, 
int iscritical 

LDAPControl **controlp,) 


Input Parameters 

ld Specifies the L D AP pointer re turned by a previous call to ldap_init() 


ldap_ssl_init() or ldap_open() 


proxyDN 

Specifies the DN of the entry whose identity the dient will assume. 


iscritical 

Specifies whether the persistent search control is critical to the search 
Operation. This should be set to a non-zero value. 


contrlp 

Pointer to a pointer of a structure that is created by this function. This 
control should be free by calling ldap_control_free() function, when it is 
done with using the control. 


Usage 

This API is used to create an LDAP control containing the proxy authorization 
identity. The created proxy authorization control will then be included in LDAP 
operations to request an Operation from the Server. 

Using the proxy authorization control mechanism, a dient can bind to the LDAP 
directory using its own identity, but is granted proxy authorization rights of 
another user to access the target directory. 

When the LDAP Server receives an Operation with proxy authorization control, the 
bind DN is validated against the administrative group and/or the predefined 
proxy authorization group to determine whether the bind DN should be granted 
the proxy authorization right. In other words, the bound application dient must be 
a member of the administrative group or proxy authorization group in Order to 
request a proxy authorization Operation. 


Errors 

LDAP_PARAM_ERROR returns if an invalid parameter was passed. 

LDAP_NO_MEMORY returns if memory cannot be allocated. 

LDAP_ENCODING_ERROR returns if an error occurred when encoding the 
control. 

LDAP_UNAVAILABLE_CRITICAL_EXTENSION returns if Server does not support 
proxy authorization and iscritical is set to a non-zero value. 

See also 


ldap Controls 

ldap_bind 

ldap_search 

ldap_modify, 

ldap_delete 

ldap_add 
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LDAP COMPARE 


ldap_compare 

ldap_compare_s 

ldap_compare_ext 

ldap_compare_ext_s 


Purpose 

Performs an LDAP compare Operation. 

Synopsis 

linclude <ldap.h> 


int 1dap_compare( 


LDAP 

*1 d. 

const char 

*dn. 

const char 

*attr. 

const char 

*value) 

dap_compare_s( 

LDAP 

*ld, 

const char 

*dn. 

const char 

*attr. 

const char 

*value) 

dap_compare_ext( 

LDAP 

*ld. 

const char 

*dn. 

const char 

*attr. 

const struct 

berval *bvalue, 

LDAPControl 

**serverctrls 

LDAPControl 

**clientctrls 

int 

*msgidp) 

dap compare ext 

s( 

LDAP 

*ld, 

const char 

*dn. 

const char 

*attr. 

const struct 

berval *bvalue, 

LDAPControl 

**serverctrl s 

LDAPControl 

**clientctrls 


Input Parameters 


ld 

dn 

attr 

bvalue 


Specifies the L D AP Pointer re turned by a previous call to ldap_init() 
ldap_ssl_init() or ldap_open() 


Specifies the DN of the entry on which to perform the comparison. 
Specifies the attribute type to use in the comparison. 

Specifies the attribute value to compare against the entry value. This 
parameter is used in the ldap_compare_ext and ldap_compare_ext_s 
routines, and is a pointer to a struct bervaL making it possible to compare 
binary values. See "LDAP_GET_VALUES" on page 77 
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serverctrls 

Specifies a list of LDAP Server Controls. This parameter can be set to 


LDAP Controls" on page 58 for more Information about Server 


NULL. See 
Controls. 

clientctrls 

Spe cifies a list of LDAP dient Co ntrols. This parameter can be set to NULL. 
See "LDAP Controls" on page 58 for more Information about dient Controls. 


Output Parameters 

msgidp 

This result parameter is set to the message ID of the request if the 
ldap_compare_ext() call succeeds. 


Usage 

The various LDAP compare routines are used to perform LDAP compare 
operations. They take dn, the DN of the entry upon which to perform the compare, 
and attr and value, the attribute type and value to compare to those found in the 
entry. 


The ldap_compare_ext() API initiates an asynchronous compare Operation and 
returns the constant LDAP_SUCCESS if the request was successfully sent, or 
another LDAP error code if it was not successfully sent. If successful, 
ldap_c ompare_extQ places the message ID of the request in * msgidp. A subsequent 
call to ldap_result() obtains the result of the Operation. After the Operation has 
completed, ldap_result() returns the Status of the Operation in the form of an error 
code. The error code indicates whether the Operation completed successfully 
(LDAP_COMPARE_TRUE or LDAP_COMPARE_FALSE). 


Similarly, the ldap_compare() API initiates an asynchronous compare Operation and 
returns the message ID of that Operation. Use a subsequent call to ldap_result() to 
obtain the result of the compare. In case of error, ldap_compare() returns -1, setting 
the session error parameters in the L DAP structure app ropriately. The session error 
Parameters can be obtained by using ldap_get_errno()| 


See "LDAP_ERROR" on page 61 for more details. 


Use the synchronous ldap_compare_s() and ldap_compare_ext_s APIs to perform 
LDAP compare operations. These APIs return an LDAP error code, which can be 
LDAP_COMPARE_TRUE if the entry contains the attribute value and 
LDAP_COMPARE_FALSE if it does not. Otherwise, some error code is returned. 


The ldap_compare_ext() and ldap_compare_ext_s() APIs both support LDAP V3 
Server Controls and dient Controls. 


Errors 


ldap compare s() API return s an LDAP error code that can be interpreted by 
calling one of the ldap_error routines. The ldap_compare() API returns -1 if the 
initiation request was unsuccessful. It returns the message ID of the request if 
successful. 


See also 

Idaperror 
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LDAP Controls 


Certain LDAP Version 3 operations can be extended with the use of Controls. 
Controls can be sent to a Server or returned to the dient with any LDAP message. 
This type of control is called a Server control. 

The LDAP API also supports a client-side extension mechanism, which can be used 
to define dient Controls. The client-side Controls affect the behavior of the LDAP 
dient library and are never sent to the Server. Note that client-side Controls are not 
defined for this dient library. 

A common data structure is used to represent both server-side and client-side 
Controls: 

typedef struct ldapcontrol { 

char *ldctl_oid; 

struct berval ldctl_value; 
char ldcLMscritical; 

} LDAPControl, *PLDAPControl; 

The LDAPControl fields have the following definitions: 

ldctl_oid 

Specifies the control type, represented as a string. 

ldctl_value 

Specifies the data associated with the control. Note that the control might 
not include data. 

ldctl_iscritical 

Specifies whether the control is critical or not. If the field is nonzero, the 
Operation is carried out only if it is recognized and supported by the 
Server or the dient for client-side Controls. 

Functions to manipulate Controls 

ldap_insert_control 

ldap_add_control 

ldap_remove_control 

ldap_copy_controls 

Purpose 

Add, remove, or copy Controls. 

Synopsis 

linclude <ldap.h> 

int 1dap_insert_control ( 

LDAPControl *newControl, 

LDAPControl ***ctrlLi st); 

int 1dap_add_control ( 

char *oid, ber_len_t len , 
char *value, 
int isCritical, 

LDAPControl ***ctrlLi st); 

int 1dap_remove_control ( 

LDAPControl *delControl, 

LDAPControl ***ctrlList, 
int freeit); 
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int ldap_copy_controls( 

LDAPControl ***to_here, 

LDAPControl **from); 

Input Parameters 

newcontrol 

Specifies a control to be inserted into a list of Controls. 

ctrlList 

Specifies a list of LDAP Server Controls 
oid Specifies the control type, represented as a string. 
len Specifies the length of the value string. 
value Specifies the data associated with the control. 

isCritical 

Specifies whether the control is critical or not. 

delControl 

Specifies the control to be deleted. 

freeit Specifies whether or not to free the control. If set to TRUE, the control will 
be freed. If set to FALSE, the control will not be freed. 

to_here 

Specifies the location to which to copy the control list. 
from Specifies the location of the control list to be copied. 

Usage 

The ldap_insert_control() API inserts the control *newcontrol into a list of Controls 
specified by ***ctrlList. The function will allocate space in the list for the control, 
but will not allocate the actual control. Returns LDAP_SUCCESS if the request was 
successfully sent or LDAP_NO_MEMORY if the control could not be inserted. 

The ldap_add_control() API creates a control (using the oid, len, value and isCritical 
values) and inserts it into a list of Controls specified by ***ctrlList. The function will 
allocate space in the list for the control. Returns LDAP_SUCCESS if the request 
was successfully sent or LDAP_NO_MEMORY if the control could not be added. 

The ldap_remove_control() API removes the control from the list. If freeit is not 0, 
the control will be freed. If freeit is set to 0, the control will not be freed. Returns 
LDAP_SUCCESS if the request was successfully sent or LDAP_NO_MEMORY if 
the control could not be removed. 

The ldap_copy_controls() API makes a copy of the control list. Returns 
LDAP_SUCCESS if the request was successfully sent or LDAP_NO_MEMORY if 
the control list could not be copied. 


LDAP_DELETE 

ldap_delete 

ldap_delete_s 

ldap_delete_ext 

ldap_delete_ext_s 
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Purpose 

Performs an LDAP Operation to delete a leaf entry. 

Synopsis 

linclude <ldap.h> 


int ldap_delete( 


LDAP 

**ld. 

const char 

*dn) 

dap_delete_s( 

LDAP 

*ld. 

const char 

*dn) 

dap delete ext( 

LDAP 

*ld. 

const char 

*dn. 

LDAPControl 

**serverctrl 

LDAPControl 

**clientctrl 

int 

*msgidp) 

dap delete ext s 

( 

LDAP 

*ld. 

const char 

*dn. 

LDAPControl 

**serverctrl 

LDAPControl 

**clientctrl 


Input Parameters 


ld Specifies the L D AP pointer re turned by a previous call to |ldap_init() 


ldap_ssl_init()| or |ldap_open() 


dn Specifies the DN of the entry to be deleted. 

serverctrls 

Specifies a list of LDAP Server Controls. This parameter can be set to 
NULL. See "LDAP Controls" on page 58 for more information about Server 
Controls. 

clientctrls 

Spe cifies a list of LDAP dient Co ntrols. This parameter can be set to NULL. 
See "LDAP Controls" on page 58 for more information about dient Controls. 


Output Parameters 

msgidp 

This result parameter is set to the message ID of the request if the 
ldap_delete_ext() call succeeds. 


Usage 


Note: The entry to delete must be a leaf entry, that is, it must have no children. 
Deletion of entire subtrees in a single Operation is not supported by LDAP. 


The ldap_delete_ext() API initiates an asynchronous delete Operation and returns 
the constant LDAP_SUCCESS if the request was successfully sent, or returns 

another LDAP error code if the request was not successful. If suc cessful, _ 

ldap_delete_ext() places the message ID of the request in *msgidp. ldap_result() 
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returns the Status of an Operation as an error code. The error code indi cates 
whether the Operation completed successfully. The ldap_parse_result() API checks 
the error code. 


Similarly, the ldap_delete() API initiates an asynchronous delete Operation and 
returns the message ID of that Operation. A subsequent call to ldap_result() can be 
used to obtain the result of the ldap_delete() Operation. In case of an error, 
ldap_delete() returns -1, setting the session error parameters in the LDAP structu re 


appropriately. These error parameters can be obtained by using ldap_get_errno() 


See 


'LDAP ERROR' 


for more details. 


Use the synchronous ldap_delete_s() and ldap_delete_ext_s() APIs to perform 
LDAP delete operations. The results of both operations are output parameters. 
These routines return either the constant LDAP_SUCCESS if the Operation was 
successful, or another LDAP error code returns if the Operation was not successful. 


Both the ldap_delete_ext() and ldap_delete_ext_s() APIs both support LDAP V3 
Server Controls and dient Controls. 


Errors 


ldap delete s() returns an LDAP error code that can be interpreted by calling an 


ldap_error routine. The ldap_delete() API returns -1 if the request initiation was 


unsuccessful. It returns the message ID of the request if successful. 


See also 

ldap_error 


LDAP_ERROR 

ldap_get_errno 

ldap_get_ldermo 

ldap_set_ldermo 

ldap_perror (deprecated) 

ldap_result2error (deprecated) 

ldap_err2string 

ldap_get_exterror 

Purpose 

LDAP protocol error handling routines. 


Synopsis 

finclude <ldap.h> 


int ldap_get_errno( 

LDAP *ld) 

int 1dap_get_lderrno ( 

LDAP *ld, 

char **dn, 

char **errmsg) 

int 1 dap_set_lderrno ( 

LDAP *1d. 
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i nt 

char 

char 


errnum, 

*dn, 

*errmsg) 


void ldap_perror( 

LDAP *1d, 

const char *s) 

int 1dap_result2error( 

LDAP *1d, 

LDAPMessage *res, 

int freeit) 

char *ldap_err2string( 

int error) 

int 1dap_get_exterror( 

LDAP *1d) 


Input Parameters 


ld 


dn 


Specifies the L D AP Pointer re turned by a previous call to |ldap_init() 


lda p_ssl_init()| or |ldap_open() 


Specifies a DN that identifies an existing entry, indicating how much of the 
name in the request was recognized by the Server. The DN is returned 
when an LDAP_NO_SUCH_OBJECT error is returned from th e Server. The 
matched DN string must be freed by calling ldap_memfree() 


errmsg 


Specifies the text of the error message, as ret urned from the Se rver. The 


error message string must be freed by calling |ldap_memfree() 


s 


res 


Specifies the message prefix, which is prepended to the string form of the 
error code held stored under the LDAP structure. The string form of the 
error is the same string that is returned by a call to ldap_err2string(). 


Specifies the result, as produced by|ldap_result()|or |ldap_search_s()| to be 


converted to the error code with which it is associated. 


freeit Specifies whether or not the result, res, must be freed as a result of calling 
ldap_result2error(). If nonzero, the result, res, is freed by the call. If zero, 
res is not freed by the call. 


errnum 


Specifies the LDAP error code, as returned by ldap_parse_result() 
another LDAP API call. 


or 


Usage 

These routines provide Interpretation of the various error codes returned by the 
LDAP protocol and LDAP library routines. 

The ldap_get_errno() and ldap_get_lderrno() APIs obtain Information for the most 
recent error that occurred for an LDAP Operation. When an error occurs at the 
LDAP Server, the Server returns the following information back to the dient: 

• The LDAP result code for the error that occurred. 

• A message containing any additional information about the error from the 
Server. 

If the error occurred because an entry specified by a DN cannot be found, the 
Server might also return the portion of the DN that identifies an existing entry. 
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Both APIs return the server's error result code. Use ldap_get_lderrno() to obtain 
the message and matched DN. 

The ldap_set_lderrno() API sets an error code and other Information about an error 
in the specified LDAP structure. This function can be called to set error 
Information that is retrieved by subsequent ldap_get_lderrno() calls. 


The ldap_result2error() routine takes res, a result as produced by ldap_result() or 
ldap search sO, and returns the corresponding error code. Possible error codes 


follow ( see 


'Errors' 


. If the freeit parameter is nonzero, it indicates that the res 


parameter must be freed by a call to ldap_msgfree() after the error code has been 
extracted. The ld ermo field in ld is set and returned. 


The returned value can be passed to ldap_err2string(), which returns a pointer to a 
character string which is a textual description of the LDAP error code. The 
character string must not be freed when use of the string is complete. 

The ldap_perror() routine can be called to print an indication of the error on 
Standard error. 


The ldap_get_exterror() routine returns the current extended error code returned 
by an LDAP Server or other library, such as Kerberos or SSL, for the LDAP session. 
For some error codes, it might be possible to further interpret the error condition. 
For example, for SSL errors the extended error code might indicate why an SSL 
handshake failed. 


Errors 

The possible values for an LDAP error code are shown in the following tables. 


Table 1. General return codes 


Dec 

value 

Value 

Hex 

value 

Brief description 

Detailed description 

00 

LDAP_SUCCESS 

00 

Success 

The request was 
successful. 

00 

LDAP_OPERATIONS_ERROR 

01 

Operations error 

An operations error 
occurred. 

02 

LDAP_PROTOCOL_ERROR 

02 

Protocol error 

A protocol violation was 
detected. 

03 

LDAP_TIMELIMIT_EXCEEDED 

03 

Time limit exceeded 

An LDAP time limit was 
exceeded. 

04 

LDAP_SIZELIMIT_EXCEEDED 

04 

Size limit exceeded 

An LDAP size limit was 
exceeded. 

05 

LDAP_COMPARE_FALSE 

05 

Compare false 

A compare Operation 
returned false. 

06 

LDAP_COMPARE_TRUE 

06 

Compare true 

A compare Operation 
returned true. 

07 

LDAP_STRONG_AUTH_NOT_SUPPORTED 

07 

Strong authentication 
not supported 

The LDAP Server does 
not Support strong 
authentication. 

08 

LDAP_STRONG_AUTH_REQUIRED 

08 

Strong authentication 
required 

Strong authentication is 
required for the 

Operation. 
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Table 1. General return codes (continued) 


Dec 

value 

Value 

Hex 

value 

Brief description 

Detailed description 

09 

LDAP_PARTIAL_RESULTS 

09 

Partial results and 
referral received 

Partial results only 
returned. 

10 

LDAP_REFERRAL 

0A 

Referral returned 

Referral returned. 

11 

LDAP_ADMIN_LIMIT_EXCEEDED 

OB 

Administration limit 
exceeded 

Administration limit 
exceeded. 

12 

LDAP_UNAVAILABLE_CRITICAL_EXTENSION 

OC 

Critical extension not 
supported 

Critical extension is not 
supported. 

13 

LDAP_CONFIDENTIALITY_REQUIRED 

OD 

Confidentiality is 
required 

Confidentiality is 
required. 

14 

LDAP_SASLBIND_IN_PROGRESS 

OE 

SASL bind in progress 

An SASL bind is in 
progress. 

16 

LDAP_NO_SUCH_ ATTRIBUTE 

10 

No such attribute 

The attribute type 
specified does not exist 
in the entry. 

17 

LDAP_UNDEFINED_TYPE 

11 

Undefined attribute 
type 

The attribute type 
specified is not valid. 

18 

LDAP_INAPPROPRIATE_MATCHING 

12 

Inappropriate matching 

Filter type not supported 
for the specified 
attribute. 

19 

LDAP_CONSTRAINT_VIOLATION 

13 

Constraint violation 

An attribute value 
specified violates some 
constraint (for example, a 
postal address has too 
many lines, or a line that 
is too long). 

20 

LDAP_TYPE_OR_VALUE_EXISTS 

14 

Type or value exists 

An attribute type or 
attribute value specified 
already exists in the 
entry. 

21 

LDAP_INVALID_SYNTAX 

15 

Invalid syntax 

An attribute value that is 
not valid was specified. 

32 

LDAP_NO_SUCH_OBJECT 

20 

No such object 

The specified object does 
not exist in the directory. 

33 

LDAP_ALIAS_PROBLEM 

21 

Alias problem 

An alias in the directory 
points to a nonexistent 
entry. 

34 

LDAP_INVALID_DN_SYNTAX 

22 

Invalid DN syntax 

A DN that is syntactically 
not valid was specified. 

35 

LDAP_IS_LEAF 

23 

Object is a leaf 

The object specified is a 
leaf. 

36 

LDAP_ALIAS_DEREF_PROBLEM 

24 

Alias dereferencing 
problem 

A problem was 
encountered when 
dereferencing an alias. 
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Table 1. General return codes (continued) 


Dec 

value 

Value 

Hex 

value 

Brief description 

Detailed description 

48 

LD AP_IN APPROPRI ATE_AUTH 

30 

Inappropriate 

authentication 

Inappropriate 
authentication was 
specified (for example, 
LDAP_AUTH_SIMPLE 
was specified and the 
entry does not have a 
userPassword attribute). 

49 

LDAP_INVALID_CREDENTIALS 

31 

Invalid credentials 

Invalid credentials were 
presented (for example, 
the wrong password). 

50 

LDAP_INSUFFICIENT_ACCESS 

32 

Insufficient access 

The user has insufficient 
access to perform the 
Operation. 

51 

LDAP_BUSY 

33 

DSA is busy 

The DSA is busy. 

52 

LDAPJJNAVAILABLE 

34 

DSA is unavailable 

The DSA is unavailable. 

53 

LDAP_UNWILLING_TO_PERFORM 

35 

DSA cannot perform 

The DSA cannot perform 
the Operation. 

54 

LDAP_LOOP_DETECT 

36 

Loop detected 

A loop was detected. 

64 

LDAP_NAMING_VIOLATION 

40 

Naming violation 

A naming violation 
occurred. 

65 

LDAP_OBJECT_CLASS_VIOLATION 

41 

Object dass violation 

An object dass violation 
occurred (for example, a 
"required" attribute was 
missing from the entry). 

66 

LDAP_NOT_ALLOWED_ON_NONLEAF 

42 

Operation not allowed 
on nonleaf 

The Operation is not 
allowed on a nonleaf 
object. 

67 

LDAP_NOT_ALLOWED_ON_RDN 

43 

Operation not allowed 
on RDN 

The Operation is not 
allowed on an RDN. 

68 

LDAP_ALREADY_EXISTS 

44 

Already exists 

The entry already exists. 

69 

LDAP_NO_OBJECT_CLASS_MODS 

45 

Cannot modify object 
dass 

Object dass modifications 
are not allowed. 

70 

LDAP_RESULTS_TOO_LARGE 

46 

Results too large 

Results too large. 

71 

LDAP_AFFECTS_MULTIPLE_DSAS 

47 

Affects multiple DSAs 

Affects multiple DSAs. 

80 

LDAP_OTHER 

50 

Unknown error 

An unknown error 
occurred. 

81 

LDAP_SERVER_DOWN 

51 

Can't contact LDAP 

Server 

The LDAP library cannot 
contact the LDAP Server. 

82 

LDAP_LOCAL_ERROR 

52 

Local error 

Some local error 
occurred. This is usually 
a failed memory 
allocation. 

83 

LDAP_ENCODING_ERROR 

53 

Encoding error 

An error was 
encountered encoding 
Parameters to send to the 
LDAP Server. 
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Table 1. General return codes (continued) 


Dec 

value 

Value 

Hex 

value 

Brief description 

Detailed description 

84 

LDAP_DECODING_ERROR 

54 

Decoding error 

An error was 
encountered decoding a 
result from the LDAP 

Server. 

85 

LDAP_TIMEOUT 

55 

Timed out 

A time limit was 
exceeded while waiting 
for a result. 

86 

LD AP_AUTH_UNKN O WN 

56 

Unknown 

authentication method 

The authentication 
method specified on a 
bind Operation is not 
known. 

87 

LDAP_FILTER_ERROR 

57 

Bad search filter 

An invalid filter was 
supplied to ldap_search 
(for example, unbalanced 
parentheses). 

88 

LD AP_U SER_C AN CELLED 

58 

User cancelled Operation 

The user cancelled the 
Operation. 

89 

LDAP_PARAM_ERROR 

59 

Bad parameter to an 
LDAP routine 

An LDAP routine was 
called with a bad 
parameter (for example, 
a NULL ld pointer, etc.). 

90 

LDAP_NO_MEMORY 

5A 

Out of memory 

A memory allocation (for 
example malloc) call 
failed in an LDAP library 
routine. 

91 

LDAP_CONNECT_ERROR 

5B 

Connection error 

Connection error. 

92 

LDAP_NOT_SUPPORTED 

5C 

Not supported 

Not supported. 

93 

LDAP_CONTROL_NOT_FOUND 

5D 

Control not found 

Control not found. 

94 

LDAP_NO_RESULTS_RETURNED 

5E 

No results returned 

No results returned. 

95 

LDAP_MORE_RESULTS_TO_RETURN 

5F 

More results to return 

More results to return. 

96 

LD AP_URL_ERR_N OTLD AP 

60 

URL doesn't begin with 
ldap:/ / 

The URL does not begin 
with ldap://. 

97 

LD AP_URL_ERR_N ODN 

61 

URL has no DN 
(required) 

The URL does not have a 
DN (required). 

98 

LDAP_URL_ERR_BADSCOPE 

62 

URL scope string is 
invalid 

The URL scope string is 
not valid. 

99 

LDAP_URL_ERR_MEM 

63 

Can't allocate memory 
space 

Cannot allocate memory 
space. 

100 

LDAP_CLIENT_LOOP 

64 

Client loop 

Client loop. 

101 

LDAP_REFERRAL_LIMIT_EXCEEDED 

65 

Referral limit exceeded 

Referral limit exceeded. 

112 

LDAP_SSL_ALREADY_INITIALIZED 

70 

ldap_ssl_client_init 
successfully called 
previously in this 
process 

The ldap_ssl_client_init 
was successfully called 
previously in this 
process. 

113 

LDAP_SSL_INITIALIZE_FAILED 

71 

Initialization call failed 

SSL Initialization call 
failed. 
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Table 1. General return codes (continued) 


Dec 

value 

Value 

Hex 

value 

Brief description 

Detailed description 

114 

LDAP_SSL_CLIENT_INIT_NOT_CALLED 

72 

Must call 

ldap_ssl_client_init 
before attempting to use 
SSL connection 

Must call 

ldap_ssl_client_init 
before attempting to use 
the SSL connection. 

115 

LDAP_SSL_PARAM_ERROR 

73 

Invalid SSL parameter 
previously specified 

An SSL parameter that 
was not valid was 
previously specified. 

116 

LDAP_SSL_HANDSHAKE_FAILED 

74 

Failed to connect to SSL 

Server 

Failed to connect to SSL 

Server. 

117 

LDAP_SSL_GET_CIPHER_FAILED 

75 

Not used 

Deprecated 

118 

LDAP_SSL_NOT_AVAILABLE 

76 

SSL library cannot be 
located 

Ensure that GSKit has 
been installed 

128 

LDAP_NO_EXPLICIT_OWNER 

80 

No explicit owner found 

No explicit owner was 
found 

129 

LDAP_NO_LOCK 

81 

Could not obtain lock 

Client library was not 
able to lock a required 
resource 


In addition, the following DNS-related error codes are defined in the ldap.h file: 
Table 2. DNS-related return codes 


Dec 

value 

Value 

Hex 

value 

Detailed description 

133 

LDAP_DNS_NO_SERVERS 

85 

No LDAP Servers found 

134 

LDAP_DNS_TRUNCATED 

86 

Warning: truncated DNS results 

135 

LDAP_DNS_INVALID_DATA 

87 

Invalid DNS Data 

136 

LDAP_DNS_RESOLVE_ERROR 

88 

Can't resolve System domain or 
nameserver 

137 

LDAP_DNS_CONF_FILE_ERROR 

89 

DNS Configuration file error 


The following UTF8-related error codes are defined in the ldap.h file: 
Table 3. UTF8-related return codes 


Dec 

value 

Value 

Hex 

value 

Detailed description 

160 

LDAP_XLATE_E2BIG 

A0 

Output buffer overflow 

161 

LDAP_XLATE_EINVAL 

Al 

Input buffer truncated 

162 

LDAP_XLATE_EILSEQ 

A2 

Unusable input character 

163 

LDAP_XLATE_NO_ENTRY 

A3 

No codeset point to map to 


See also 


ldap_memfree ldap_parse routines 
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LDAP_EXTENDED_OPERATION 

ldap_extended_operation 

ldap_extended_operation_s 


Purpose 

Performs extended operations and parse extended result. 

Synopsis 

linclude <ldap.h> 


i nt 


i nt 


1dap_extended_operat i on( 

LDAP *ld, 

const char *reqoid, 

const struct berval *reqdata, 
LDAPControl **serverctrls, 

LDAPControl **clientctrls, 

int *msgidp) 


1dap_extended_operation_s( 


LDAP 
const char 


*ld, 

*reqoid. 


const struct berval *reqdata, 


LDAPControl 

LDAPControl 

char 


**serverctrls, 
**clientctrls, 
**retoidp. 


struct berval **retdatap) 


Input Parameters 


ld Specifies the L D AP pointer re turned by a previous call to |ldap_init() 


ldap_ssl_init()| or |ldap_open() 


reqoid Specifies the dotted-object identifier (OID) text string that identifies the 
extended Operation to be performed by the Server. 

reqdata 

Specifies the arbitrary data required by the extended Operation (if NULL, 
no data is sent to the Server). 

serverctrls 

Specifies a list of LDAP Server Controls. This parameter can be set to 
NULL. See "LDAP Controls" on page 58 for more information about Server 
Controls. 

clientctrls 

Spe cifies a list of LDAP dient Co ntrols. This parameter can be set to NULL. 


See 


'LDAP Controls" on page 58 


for more information about dient Controls. 


Output Parameters 

msgidp 


This result parameter is set to the message ID of the request if the 
ldap_extended_operation() call is s uccessfully sen t to the Server. To check 


the result of this Operation, call the ldap_result() and ldap_parse_result() 


APIs. The Server can also return an OID and result data. Because the 
asynchronous ldap_extended_operation does not directly return the results, 
use ldap_parse_extended_result() to get the results. 
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retoidp 


This result parameter is set to point to a character string that is set to an 
allocated, dotted-OID te xt string returned from the Server. This string must 
be disposed of using the ldap_memfree() API. If no OID is returned, 
"retoidp is set to NULL. 


retdatap 

This result parameter is set to a pointer to a berval structure pointer that is 
set to an allocated copy of the data returned by the Server. This struct 
berval must be disposed of using ber_bvfree(). If no data is returned, 
"'retdatap is set to NULL. 


Usage 

The ldap_extended_operation() function is used to initiate an asynchronous 
extended Operation, which returns LDAP_SUCCESS if the extended Operation was 
successfully sent, or an LDAP error code is returned if the Operation was not 



response. 


The ldap_extended_operation_s() function is used to initiate a synchronous 
extended Operation, which returns the result of the Operation: either 
LDAP_SUCCESS if the Operation was successful, or it returns another LDAP error 
code if it was not successful. The retoid and retdata parameters are filled in with 
the OID and data from the response. If no OID or data was returned, these 
parameters are set to NULL. 

If the LDAP Server does not support the extended Operation, the Server rejects the 
request. IBM Tivoli Directory Server Version 5.2 provides a Server plug-in interface 
that can be used to add extended Operation support. For more information, see the 
IBM Directory Server Version 5.2: Server Plug-ins Reference. 


To determine if the requisite extended Operation is supported by the Server, get the 
rootDSE of the LDAP Server and check for the supportedExtension attribute. If the 
values for this attribute include the OID of your extended Operation, then the 
Server supports the extended Operation. If the supportedExtension attribute is not 
present in the rootDSE, then the Server is not configured to support any extended 
opera tions. 


A list of OIDs for supported extended operations can be found in A^pendixF) 


'Object Identifiers (OIDs) for extended operations and Controls", on page 189 


Errors 

The ldap_extended_operation_s() API returns the LDAP error code for the 
Operation. 


The ldap_extended_operation() API returns -1 instead of a valid msgid if an error 
occurs, setting the session error in t he LD structure. The Session error can be 


obtained by using ldap_get_errno() 


See "LDAP_ERROR" on page 61 for more details. 
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Notes 


These routines allocate storage. Use ldap_memfree to free the returned OID. Use 
ber bvfree to free the returned struct berval. 


See also 


ldap_result ldap_error 


LDAP_FIRST_ATTRIBUTE 

ldap_count_attributes 

ldap_first_attribute 

ldap_next_attribute 


Purpose 

Step through LDAP entry attributes. 

Synopsis 

linclude <ldap.h> 


int 1dap_count_attri butes( 

LDAP *ld, 

LDAPMessage *entry) 

char *ldap_first_attribute( 

LDAP *ld, 

LDAPMessage *entry, 

BerElement **berptr) 

char *ldap_next_attribute( 

LDAP *ld, 

LDAPMessage *entry, 

BerElement *berptr) 


Input Parameters 


ld Specifies the L D AP pointer re turned by a previous call to ldap_init() 


ldap_ssl_init() or ldap_open() 


Output Parameters 

berptr 

This is an output parameter returned from ldap_first_attribute(), which 
returns a pointer to a BerElement that has been allocated to keep track of 
current position. It is an input and output parameter for subsequent calls 
to ldap_next_attribute(), where it specifies a pointer to a BerElement that 
was allocated by the previous call to ldap_first_attribute(). The BerElement 
structure is opaque to the application. 


Usage 

The ldap_count_attributes() routine returns a count of the number of attributes in 
an LDAP entry It a NULL entry is returned from ldap_first_entry() or 
ldap_next_entry(), and is passed as input to ldap_count_attributes(), -1 is returned. 

The ldap_first_attribute() and ldap_next_attribute() routines are used to step 
through the attributes in an LDAP entry. 
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ldap_first_attribut e() takes an entry as returned by ldap_first_entry() or 
ldap_next_entry() and retums a pointer to a buffer containing the first attribute 
type in the entry. 

The pointer returned by ldap_first_attribute in berptr must be passed to 
subsequent calls to ldap_next_attribute and is used to step through the entry's 
attributes. When there are no attributes left to be retrieved, ldap_next_attribute() 
returns NULL and sets the error code to LDAP_SUCCESS. If an error occurs, 
NULL is returned and an error code is set. The memor y allocated for the 


BerElement buffer must be freed using ldap_ber_free() 


Therefore, when NULL is returned, the ldap_get_errno() 


determine whether or not an error has occurred. 


API must be used to 


If the caller fails to call ldap_next_attribute() a sufficient number of times to 
exhaust the list of attributes, the caller is responsible for fre eing the BerElem ent 


pointed to by berptr when it is no longer needed by calling |ldap_ber_free() 


The attribute names returned by ldap_first_attribute() and ldap_next_attribute() are 
suitable for inclusion in a call to ldap_get_values(). 

ldap_next_attribute() returns a string that contains the name of the next type in the 
entry This string must be freed using ldap_memfree() when its use is completed. 


The attr ibute names return ed by ldap_next_attribute() are suitable for inclusion in 
a call to ldap_get_values() to retrieve the attribute's values. 


Errors 

If the ldap_first_attribute() call results in an error, then NULL is returned, the error 
code is set. 


The lda£^et_ermo£2 API can be used to obtain the error code. See 


'LDAP ERROR" on page 61 for a description of possible error codes. 


Notes 

The ldap_first_attribute() and ldap_next_attribute() routines allocate memory that 
might need to be freed by the caller through ldap_memfree. 

See also 


ldap_first_entry, 

ldap_get_values 

ldap_memfree 

ldap_error 


LDAP_FIRST_ENTRY, LDAP_FIRST_REFERENCE 

ldap_first_entry 

ldap_next_entry 

ldap_count_entries 

ldap_get_entry_controls 

ldap_first_reference 

ldap_next_reference 

ldap_count_references 

ldap_parse_reference 
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Purpose 


LDAP result entry and continuation reference parsing and counting routines. Note 
that APIs with the _np suffix are preliminary implementations, and are not 


documented in the Internet Draft, "C LDAP Application Program Interface" 


Synopsis 

linclude <ldap.h> 


LDAPMessage *ldap first entry( 

LDAP *1d, 

LDAPMessage *result) 

LDAPMessage *ldap next entry( 

LDAP *1d, 

LDAPMessage *entry) 

int 1dap_count_entries( 

LDAP *1d, 

LDAPMessage *result) 

int 1dap_get_entry_controls_np( 

LDAP *1d, 

LDAPMessage *entry 

LDAPControl ***serverctrlsp) 

LDAPMessage *1dap_first_reference( 

LDAP *1d, 

LDAPMessage *result) 


LDAPMessage *1 dap_next_reference( 

LDAP *1d, 

LDAPMessage *ref) 

LDAPMessage *result) 

int 1dap_count_references( 

LDAP *1d, 

LDAPMessage *result) 


int ldap_parse_reference_np( 
LDAP 

LDAPMessage 

char 

LDAPControl 
i nt 


*1 d, 

*ref, 

***referral sp, 
***serverctrl sp, 
freeit ) 


Input Parameters 


ld Specifies the L D AP pointer re turned by a previous call to |ldap_init() 
ldap_ssl_init() or ldap_open() 


result Specifies the result returned by a call to ldap_result() or one of the 

synchronous search routines, such as ldap_search_s(), ldap_search_st() or 
ldap_search_ext_s(). 


entry Specifies a pointer to an entry returned on a previous call to 
ldap_first_entry() or ldap_next_entry(). 


serverctrlsp 

Specifies a pointer to a result parameter that is filled in with an allocated 
array of Controls copied out of the LDAPMessage m essage. The control 


array must be freed by calling |ldap_controls_free() 
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ref Specifies a pointer to a search continuation reference returned on a 
previous call to ldap_first_reference() or ldap_next_reference(). 

referralsp 

Specifies a pointer to a result parameter that is filled in with the contents 
of the referrals field from the LDAPMessage message. The LDAPMessage 
message indicates zero or more alternate LDAP Servers where the request 
must be retried. T he referrals array must be freed by calling 


ldap_value_free() Supply NULL for this parameter to ignore the referrals 


freeit 


field. 

Specifies a Boolean value that determines if the LDAP result chain, as 
specified by ref, is to be freed. Any nonzero value results in the LDAP 
result chain bein g freed after the requested information is extracted. 


Alternatively, the ldap_msgfree() 
chain at a later time. 


API can be used to free the LDAP result 


Usage 

These routines are used to parse results received from ldap_result() or the 
synchronous LDAP search Operation routines ldap_search_s(), ldap_search_st(), and 
ldap_search_ext_s(). 


Processing entries 

The ldap_first_entry() and ldap_next_entry() APIs are used to step through and 
retrieve the list of entries from a search result chain. When an LDAP Operation 
completes and the result is obtained as described, a list of LDAPMessage structures 
is returned. This list is referred to as the search res ult chain. A poin ter to the first 


of these structures is returned by |ldap_result()| and |ldap_search_s() 


The ldap_first_entry() routine is used to retrieve the first entry in a chain of search 
results. It takes the result returned by a call to ldap_result(), ldap_search_s(), 
ldap_search_st() or ldap_search_ext_s() and retums a pointer to the first entry in 
the result. 


This pointer must be supplied on a subsequent call to ldap_next_entry() to get the 
next entry, and so on until ldap_next_entry() returns NULL. The ldap_next_entry() 
API returns NULL when there are no more entries. The entries returned from these 
calls are used in calls to the routines ldap_get_dn(), ldap_first_attribute(), 
ldap_get_values(), and so forth. 

The ldap_get_entry_controls_np() routine is used to retrieve an array of Server 
Controls returned in an individual entry in a chain of search results. 

Processing continuation references 

The ldap_first_reference() and ldap_next_reference() APIs are used to step through 
and retrieve the list of continuation references from a search result chain. They 
return NULL when no more continuation references exist in the result set to be 
returned. 


The ldap_first_reference() routine is used to retrieve the first continuation reference 
in a chain of search results. It takes the result as returned by a call to ldap_result(), 
ldap_search_s(), ldap_search_st(), or ldap_search_ext_s() and returns a pointer to 
the first continuation reference in the result. 


The pointer returned from ldap_first_reference() must be supplied on a subsequent 
call to ldap_next_reference() to get the next continuation reference. 
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The ldap_parse_reference_np() routine is used to retrieve the list of alternate 
Servers returned in an individual continuation reference in a chain of search 
results. This routine is also used to obtain an array of Server Controls returned in 
the continuation reference. 

Counting entries and references 

The ldap_count_entries() API retums the number of entries contained in a search 
result chain. It can also be used to count the number of entries that remain in a 
chain if called with a message, entry, or continuation reference returned by 
ldap_first_message(), I d ap_nex t_message(), ldap_first_entry(), ldap_next_entry(), 
ldap_first_reference() or ldap_next_reference(). 

The ldap_count_references() API is used to count the number of continuation 
references returned. It can also be used to count the number of continuation 
references that remain in a chain. 


Errors 


If an error occurs in ldap_first_entry(), ldap next entryQ, ldap first referenceQ, or 
ldap_next_reference(), NULL is returned, and ldap_get_errno() API can be used to 
obtain the error code. 


If an error occurs in ldap_count_entries() or ldap_count_references(), -1 is returned, 
and ldap_get_ermo() can be used to obtain the error code. The 
ldap_get_entry_controls_np() and ldap_parse_reference_np() APIs return an LDAP 
error code directly, for example, LDAP_SUCCESS if the call was successful, an 
LDAP error if the call was unsuccessful. 


See |"LDAP_ERROR" on page 61 for a description of possible error codes. 

See also 


ldap_result() ldap_search() ldap_first_attribute() ldap_get_values() ldap_get_dn() 


LDAP_GET_BIND_CONTROLS 


ldap_get_bind_controls 


Purpose 

Allows dient using ldap_sasl_bind_s to get Controls sent by the Server. 

Synopsis 

int 1dap_get_bind_controls ( 

LDAP *1d, 

LDAPControl ***bind_controls ); 

Input Parameters 

ld Specifies the LDAP pointer returned by a previous call to ldap_init(), 
ldap_ssl_init() or ldap_open(). 

Output Parameters 

bind_controls 

This result parameter is set to the Controls the Server returned to the dient 
during the previous call to ldap_sasl_bind_s(). 
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Usage 


After calling ldap_sasl_bind_s(), the application calls ldap_get_bind_controls() to 
gef a NULL-terminated array of the Controls that the Server returned on the bind. 
If the caller has not called ldap_sasl_bind_s() for the supplied Id, the dient will set 
bind_controls to NULL. 


Errors 


The ldap get bind controlsO AP I returns the LDAP error code for the Operation. 


See 


'LDAP_ERROR" on page 61 for a description of possible error codes. 


Notes 

This routine allocates memory for Controls that it returns. The memory can be 
deallocated by calling ldap_controls_free(). 

See also 


LDAP Controls LDAP ERROR 

LDAP PASSWORD POLICY, 

ldap sasl bind s() 

ldap controls freeO 


LDAP_GET_DN 

ldap_dn2ufn 

ldap_get_dn 

ldap_explode_dn 

ldap_explode_dns 

ldap_explode_rdn 


Purpose 

LDAP DN and RDN handling routines. 

Synopsis 

finclude <ldap.h> 


char *1dap_dn2ufn( 

const char *dn) 

char *1dap_get_dn( 

LDAP *1d, 

LDAPMessage *entry) 

char **ldap_explode_dn( 
const char *dn, 
int notypes) 

char **1 dap_explode_dns( 
const char *dn) 

char **ldap_explode_rdn( 
const char *rdn, 
int notypes) 


Input Parameters 


ld 


Specifies the L D AP pointer ret urned by a previous call to |ldap_init() 


ldap_ssl_init()[ or |ldap_open() 
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dn Specifies the DN to be exploded (as returned from ldap_get_dn()) or 
converted to a simple form (as returned from ldap_dn2ufn()). 

rdn Specifies the RDN to be exploded (as returned from ldap_explode_dn()). 

entry Specifies he entry whose dn is to be retrieved. 

notypes 

Specifies if type names are to be returned for each RDN. If nonzero, the 
type information is stripped. If zero, the type Information is retained. For 
example, setting notypes to 1 can result in the RDN "cn=Fido" being 
returned as Fido. 


Usage 

The ldap_dn2ufn() routine takes a DN and converts it into a simple representation 
by removing the attribute type that is associated with each RDN. For example, the 
DN "cn=John Doe, ou=Widget Division, ou=Austin, o=IBM, c=US" is returned in 
its simple form as "John Doe, Widget Division, Austin, IBM, US". Space for the 
simple name is o btained by the LDAP API, and must be freed by a call to 
ldap_memfree() 


The ldap gef dn() routine takes an entry as returned by |ldap_first_entry() 


or 


ldap_next_entry() and returns a copy of the entry's DN. Space for the DN is 


obtained by the LDAP API, and must be freed by a call to ldap_memfree(). 


The ldap_explode_dn() routine takes a DN (perhaps as returned by ldap_get_dn()) 
and breaks it up into its component parts. Each part is known as a Relative 
Distinguished Name, or RDN. The ldap_explode_dn() API returns a 
NULL-terminated array of character strings, each component of which contains an 
RDN from the DN. The notypes parameter is used to request that only the RDN 
values, and not their types, be returned. For example, the DN "cn=Bob,c=US" 
returns an array as either {"cn=Bob","c=US",NULL) or {"Bob","US",NULL[ 
depending on wh ether notypes was 0 or 1. The result can be freed by calling 
ldap_value_free() 


The ldap_explode_dns() routine takes a DNS-style DN and breaks it up into its 
component parts. It returns a NULL-terminated array of character strings. For 
example, the DN "austin.ibm.com" returns { "austin", "ibm", "com", NULL }. The 
result can be freed by calling ldap_value_free(). 

The ldap_explode_rdn() routine takes an RDN (perhaps as returned by 
ldap_explode_dn() ) and breaks it up into its component parts. The 
ldap_explode_rdn() API returns a NULL-terminated array of character strings. The 
notypes parameter is used to request that only the component values be returned, 
not their types. For example, the RDN "ou=Research + cn=Bob" returns as either 
{"ou=Research", "cn=Bob", NULL} or {"Research'V'Bob", NULL}, depending on 
whether notypes was 0 or 1. The result can be freed by calling ldap_value_free(). 

The dient DN processing functions normalize attribute values that contain 
compound RDNs, escaped hex representations of UTF-8 characters and 
ber-encoded values. The functions also check that the DN passed in is in a correct 
format according to RFC 2253. ldap_explode_rdn removes back slashes ( \ ) from 
in front of special characters. 

Idap_dn2ufn, ldap_explode_dn and ldap_explode_rdn normalize attribute values 
by doing the following: 
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• A back slash followed by a two-digit hex representation of a UTF-8 character is 
converted to the character representation. For example, cn=\4A\6F\68\6E Doe is 
converted to cn=John Doe. 

• A ber-encoded value is converted to a UTF-8 value. For example, 
cn=#04044A6F686E2G446F65 is converted to cn=John Doe. 

Idap_dn2ufn, ldap_explode_dn and ldap_explode_rdn check that the DN passed in 
is valid. If the DN is invalid, NULL is returned. A DN is invalid if the attribute 
type or value are in invalid formats. See RFC 2253 for more specific information. 

Idap_dn2ufn, ldap_explode_dn and ldap_explode_rdn handle compound RDNs. 
For example: 

• The DN cn=John+sn=Doe passed into ldap_dn2ufn returns John+Doe 

• ldap_explode_dn with notype returns John+Doe 

• ldap_explode_rdn with notype returns [0]=John [l]=Doe 

ldap_explode_rdn removes the back slash from in front of special characters. For 
example, when calling 

ldap_explode_rdn(cn=Doe\<Jane+ou=LDAP+o=IBM+c=US,l), ldap_explode_rdn 
returned: 

• [0] = Doecjane 

• [1] = LDAP 

• [2] = IBM 

• [3] - US 


Errors 


If an error occurs in ldap_dn2ufn(), ldap_get_dn(), ldap_explode_dn(), or 
ldap_explode_rdn (), NULL is returned. If ldap_get_dn() return s NULL, the 


jdap=get_errno() API can be used to obtain the error code. See "LDAP_ERROR" on 


page 61| for a description of possible error codes. 


Notes 

These routines allocate memory that the caller must deallocate. 


See also 


ldap_first_entry, ldap_error ldap_value_free 


LDAP_GET_VALUES 

ldap_get_values 

ldap_get_values_len 

ldap_count_values 

ldap_count_values_len 

ldap_value_free 

ldap_value_free_len 

Purpose 

LDAP attribute value handling routines. 
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Synopsis 

linclude <ldap.h> 


struct berval { 

unsigned long bv_len; 
char *bv_val; 

}; 


char **1dap_get_values( 


LDAP 

*ld. 

LDAPMessage 

*entry, 

const char 

*attr) 

struct berval **ldap get 

; values 

LDAP 

*ld. 

LDAPMessage 

*entry, 

const char 

*attr) 

int Idap count values( 

char 

**vals) 


int 1dap_count_values_len( 

struct berval **bvals) 

void 1dap_value_free( 

char **vals) 

void ldap_value_free_len( 

struct berval **bvals) 


Input Parameters 


Usage 


ld Specifies the L D AP pointer re turned by a previous call to ldap_init() 


attr 

entry 


ldap_ssl_init()| or |ldap_open() 


Specifies the attribute whose values are desired. 


Specifies an LDAP entry as returned from ldap_first_entry() 


ldap_next_entry() 


or 


vals Specifies a pointer to a NULL- terminated array of attribute values, as 


returned by |ldap_get_values() 


bvals 


Specifies a pointer to a NULL-terminated array of pointers to berval 
structures, as returned by ldap_get_values_len(). 


These routines are u sed to retrieve and m anipulate attribute values from an LDAP 
entry as returned by ldap_first_entry() or ldap_next_entry() 


An attribute's values can be represented in two forms: 

• A NULL-terminated array of strings. This representation is appropriate when the 
attribute contains string data, for example, a title, description or name. 

• A NULL-terminated array of berval structures. This representation is appropriate 
when the attribute contains binary data, for example, a JPEG file. 

String values 

Use ldap_get_values() to obtain attribute values as an array of strings. The 
ldap_get_values() API takes the entry and the attribute attr whose values are 
desired and returns a NULL-terminated array of character strings that represent 
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the attribute's values . T he attr cart be an attri bute type as returned from 


ldap_first_attribute() or ldap_next_attribute() or if the attribute type is known it 


can simply be provided. 


The number of values in the array of character strings can be counted by calling 
ldap_count_values(). The array of values returned can be freed by calling 
ldap_value_free(). 


If your application is designed to rely on the LDAP library to convert LDAP V3 
string data f rom UTF-8 to the l ocal code page (enabled on a per-connection basis 
by using the 


ldap_set_option() API with the LDAP_OPT_UTF8_IO), strings 


returned in the NULL-terminated array of string values can contain multi-byte 
characters, as defined in the local code page. In this case, the application must use 
string handling routines that are properly enabled to handle multi-byte strings. 


Binary values 

If the attribute values are binary in nature, and thus not suitable to be returned as 
an array of character strings, the ldap_get_values_len() routine can be used instead. 
It takes the same parameters as ldap_get_values() but returns a NULL-terminated 
array of pointers to berval structures, each containing the length of, and a pointer 
to, a value. 


The number of values in the array of bervals can be counted by calling 
ldap_count_values_len(). The array of values returned can be freed by calling 
ldap_value_f ree_len(). 


Errors 


If an er ror occurs in ldap _get_values() or ldap_get_values_len(), NULL is returned 
and the ldap_get_errno() API can be used to obtain the error code. See 


'LDAP ERROR" on page 61|for a description of possible error codes. 


See also 


ldap_first_entry, ldap_first_attribute ldap_error 


LDAPJNIT 

ldap_init 

ldap_open (deprecated) 
ldap_set_option 
ldap_get_option 
ldap_version 


Purpose 

Initializes the LDAP library, opens a connection to an LDAP Server, and gets or 
sets options for an LDAP connection. 

Synopsis 

finclude <ldap.h> 


LDAP *ldap_init( 

const char *host, 
int port) 
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LDAP *ldap_open( 

const char *host, 
int port) 

int ldap_set_option( 

LDAP *ld, 

int optionToSet, 

void *optionValue) 

int ldap_get_option( 

LDAP *ld, 

int optionToGet, 

void *optionValue) 

int ldap_version( 

LDAPVersion *version) 


Input Parameters 


ld Specifies the L D AP pointer re turned by a previous call to |ldap_init() 


ldap_ssl_init()| or |ldap_open() 


host Several methods are supported for specifying one or more target LDAP 
Servers, including the following: 


Explicit Host List 

Specifies the name of the host on which the LDAP Server is 
running. The host parameter can contain a blank-separated list of 
hosts to try to connect to, and each host can optionally be of the 
form host:port. If present, the :port Overrides the port parameter 
supplied on ldap_init(), ldap_ssl_init() or ldap_open(). The 
following are typical examples: 

1d=ldap_init ("serverl", ldap_port); 
ld=ldap_init ("server2:1200", ldap_port); 

1 d=ldap_init ( "serverl:800 server2:200O server3", ldap_port); 


Localhost 

If the host parameter is NULL, the LDAP Server is assumed to be 
running on the local host. 


Default Hosts 

If the host parameter is set to "ldap://" the LDAP library attempts 
to locate one or more default L DAP Servers, with no n-SSL ports, 
using the IBM Directory Server ldap_server_locate() function. The 
port specified on the call is ignored, because ldap_server_locate() 
returns the port. For example, the following are equivalent: 

1d=ldap_init ("ldap://", ldap_port); 


and 

ld=ldap_init (LDAP_URL_PREFIX, LDAP_P0RT); 


If more than one default Server is located, the list is processed in 
sequence until an active Server is found. 

The LDAP URL can include a distinguished name, used as a filter 
for selecting candidate LDAP Servers based on the server's suffixes. 
If the most significant portion of the DN is an exact match with a 
server's suffix after normalizing for case, the Server is added to the 
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list of candidate Servers. For example, the following example 
returns default LDAP Servers that have a suffix that supports the 
specified DN only: 

ld=ldap_init ("ldap:///cn=fred, dc=austin, 
dc=ibm, dc=com", LDAP_P0RT); 

In this case, a Server that has a suffix of "dc=austin, dc=ibm, 
dc=com" matches. If more than one default Server is located, the 
list is processed in sequence, until an active Server is found. 

If the LDAP URL contains a host name and optional port, the host 
is used to create the connection. No attempt is made to locate the 
default Servers, and the DN, if present, is ignored. For example, the 
following examples are equivalent: 
ld=ldap_init ("ldap://myserver", LDAP_P0RT); 


and 

ld=ldap_init ("myserver", LDAP_P0RT); 


See pLocating default LDAP Servers" on page 90| for more 
Information about the algorithm used to locate default LDAP 


Servers. 


Local Socket 

If the host parameter is prefixed with a forward slash ( / ), the 
host parameter is assumed to be the name of a UNIX socket, that 
is, family is AF_UNIX, and port is ignored. Use of a UNIX socket 
requires the LDAP Server to be running on the local host. In 
addition, the local operating System must support UNIX sockets 
and the LDAP Server must be listening on the specified UNIX 
socket. UNIX variants of the IBM Directory Server listen on the 
/tmp/s.slapd local socket, in addition to any configured TCP/IP 
ports. For example: 

ld=ldap_init ("/tmp/s.slapd", ldap_port); 

Host with Privileged Port 

On platforms that support the rresvport function, typically UNIX 
platforms, if a specified host is prefixed with "privport://", then 
the LDAP library uses the rresvport() function to attempt to obtain 
one of the reserved ports (512 through 1023), instead of an 
ephemeral port. The search for a reserved port Starts at 1023 and 
stops at 512. If a reserved port cannot be obtained, the function call 
fails. For example: 

ld=ldap_init ("privport://serverl", ldap_port); 
ld=ldap_init ("privport://server2:12O0", ldap_port); 
ld=ldap_init ("privport://serverl:80O server2:2O0O 
privport://server3", ldap_port); 


port Specifies the port number to connect to. If the default IANA-assigned port 
of 389 is desired, LDAP_PORT must be specified. To use the default SSL 
port 636 for SSL connections, use LDAPS_PORT. 


optionToSet 

Ide ntities the Option valu e that is to be set on the ldap_set_option() call. 


See 


'Usage" on page 82 for the list of supported options. 
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optionToGet 

Identifie s the Opti on value that is to be queried on the ldap_get_option() 


call. See "Usage" for the list of supported options. 


Option Value 

Specifies the address of the value to set using ldap_set_option() or the 
address of the storage in which the queried value is returned using 
ldap_get_option(). 


Version 

Specifies the address of an LDAPVersion structure that contains the 
following returned values: 

sdk_version 

SDK version, multiplied by 100. 
protocol_version 

Highest LDAP protocol supported, multiplied by 100. 
SSL_version 

SSL version supported, multiplied by 100. 
security_level 

Level of encryption supported, in bits. Set to 
LDAP_SECURITY_NONE if SSL not enabled. 


ssl_max_cipher 

A string containing the default ordered set of ciphers supported by 
this Installation. See l'T D AP SET OPTION syntax for LDAP V2 


applications" on page 89 for more information about changing the 
set of ciphers used to negotiate the secure connection with the 


Server. 


sdk_vendor 

A pointer to a static string that identifies the supplier of the LDAP 
library. This string must not be freed by the application. 

sdk_build_level 

A pointer to a static string that identifies the build level, including 
the date when the library was built. This string must not be freed 
by the application. 


Usage 

The ldap_init() API initializes a session with an LDAP Server. The Server is not 
actually contacted until an Operation is performed that requires the Server, 
allowing various options to be set after initialization, but before actually contacting 
the host. It allocates an LDAP structure that is used to identify the connection and 
maintain per-connection information. 

Although still supported, ldap_open() is deprecated. The ldap_open() API allocates 
an LDAP structure and opens a connection to the LDAP Server. Use ldap_init() 
instead of ldap_open(). 

The ldap_init() and ldap_open() APIs return a pointer to an LDAP structure, which 
must be passed to subsequent calls to ldap_set_option(), ldap_simple_bind(), 
ldap_search(), and so forth. 


The LDAP structure is opaque to the application. Direct manipulation of the LDAP 
structure is not recommended. The ldap_version() API returns th e toolkit version 
(multiplied by 100). It also sets information in the LDAPVersion structure (see 82 . 
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Setting and getting session settings 

The ldap_set_option() API sets options for the specified LDAP connection. The 
ldap_get_option() API queries settings associated with the specified LDAP 
connection. 

The following session settings can be set and retrieved using the ldap_set_option() 
and ldap_get_option() APIs: 

LDAP_OPT_SIZELIMIT 

Get or set maximum number of entries that can be returned on a search 
Operation. 

LDAP_OPT_TIMELIMIT 

Get or set maximum number of seconds to wait for search results. 

LDAP_OPT_REFHOPLIMIT 

Get or set maximum number of referrals in a sequence that the dient can 
follow. 



Get or set mode for converting string data between the local code page 
and UTF-8. 



Get extended error code. 
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See "LDAP SET OPTION syntax for LDAP V2 applications" on page 89 for 


important information if your LDAP application is based on the LDAP V2 APIs 
and uses the ldap_set_option() or ldap_get_option() functions; that is, you are 
using ldap_open, or your application uses ldap_init() and ldap_set_option() to 
switch from the default of LDAP V3 to use the LDAP V2 protocol and 
subsequently uses the ldap_set_option() or ldap_get_option() calls. 


Additional details on specific options for ldap_set_option() and ldap_get_option() 
are provided in the following sections. 

LDAP_OPT_SIZELIMIT: Specifies the maximum number of entries that can be 
returned on a search Operation. 

Note: The actual size limit for operations is also bounded by the maximum 
number of entries that the Server is configured to return. Therefore, the 
actual size limit is the lesser of the value specified on this Option and the 
value configured in the LDAP Server. 


The default sizelimit is unlimited, specified with a value of zero, thus deferring to 
the sizelimit setting of the LDAP Server. 

For example: 
sizevalue=50; 

1dap_set_option( ld, LDAP_OPT_SIZELIMIT, &sizevalue); 

1dap_get_option( ld, LDAP_OPT_SIZELIMIT, &sizevalue); 

LDAP_OPT_TIMELIMIT: Specifies the number of seconds to wait for search 
results. 


Note: The actual time limit for opera tions is also bounded by the maximum time 
that the Server is configured to allow. Therefore, the actual time limit is the 
lesser of the value specified on this Option and the value configured in the 
LDAP Server. 

The default is unlimited (specified with a value of zero). For example: 
timevalue=50; 

1dap_set_option( ld, LDAP_OPT_TIMELIMIT, &timevalue); 

1dap_get_option( ld, LDAP_OPT_TIMELIMIT, &timevalue); 

LDAP_OPT_REFHOPLIMIT: Specifies the maximum number of hops that the 
dient library takes when chasing referrals. The default is 10. For example: 
hoplimit=7; 

1dap_set_option( ld, LDAP_0PT_REFH0PLIMIT, &hoplimit); 

1dap_get_option( ld, LDAP_0PT_REFH0PLIMIT, &hoplimit); 

LDAP_OPT_DEREF: Specifies alternative rules for following aliases at the Server. 
The default is LDAP_DEREF_NEVER. 

Supported values: 

LDAP_DEREF_NEVER 0 
LDAP_DEREF_SEARCHING 1 
LDAP_DEREF_FINDING 2 
LDAP_DEREF_ALWAYS 3 

For example: 
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int deref = LDAP_DEREF_NEVER; 

1dap_set_option( ld, LDAP_OPT_DEREF, &deref); 

1dap_get_option( ld, LDAP_OPT_DEREF, &deref); 

LDAP_OPT_REFERRALS: Specifies whether the LDAP library automatically 
follows referrals returned by LDAP Servers or not. It can be set to one of the 
constants LDAP_OPT_ON or LDAP_OPT_OFF. By default, the LDAP dient follows 
referrals. For example: 
int value; 

1dap_set_option( ld, LDAP_OPT_REFFERALS, (void *)LDAP_0PT_0N); 

1dap_get_option( ld, LDAP_OPT_REFFERALS, &value); 


LDAP_OPT_DEBUG: Specifies a bitmap that indicates the level of debug trace 
for the LDAP library. 

Supported values: 

/* Debug levels */ 


LDAP_DEBUG_OFF 0x000 

LDAP_DEBUG_TRACE 0x001 

LDAP_DEBUG_PACKETS 0x002 

LDAP_DEBUG_ARGS 0x004 

LDAP_DEBUG_CONNS 0x008 

LDAP_DEBUG_BER 0x010 

LDAP_DEBUG_FILTER 0x020 

LDAP_DEBUG_C0NFIG 0x040 

LDAP_DEBUG_ACL 0x080 

LDAP_DEBUG_STATS 0x100 

LDAP_DEBUG_STATS2 0x200 

LDAP_DEBUG_SHELL 0x400 

LDAP_DEBUG_PARSE 0x800 

LDAP DEBUG ANY Oxffff 


For example: 
int value; 

int debugvalue= LDAP_DEBUG_TRACE | LDAP_DEBUG_PACKETS; 

1dap_set_option( ld, LDAP_0PT_DEBUG, &debugvalue); 

1dap_get_option( ld, LDAP_0PT_DEBUG, &value ); 

LDAP_OPT_SSL_CIPHER: Specifies a set of one or more ciphers to be used 
when negotiating the cipher algorithm with the LDAP Server. Choose the first 
cipher in the list that is common with the list of ciphers supported by the Server. 
The default value is "05040A090306". 


Note: If you try to get an SSL cipher and you are not running on an SSL Version of 
IBM Directory Server, an error is returned. 

Supported ciphers: 

LDAP_SSL_RC4_MD5_EX "03" 

LDAP_SSL_RC2_MD5_EX "06" 

LDAP_SSL_RC4_SHA_US "05" 

LDAP_SSL_RC4_MD5_US "04" 

LDAP_SSL_DES_SHA_US "09" 

LDAP_SSL_3DES_SHA_US "0A" 

For example: 
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char *setcipher = "090A"; 
char *getcipher; 

1dap_set_option( ld, LDAP_OPT_SSL_CIPHER, setcipher); 

1dap_get_option( ld, LDAP_OPT_SSL_CIPHER, &getcipher ); 


Use 


ldap_memfree() to free the memory returned by the call to ldap_get_option(). 


LDAP_OPT_SSL_TIMEOUT: Specifies in seconds the SSL inactivity timer. After 
the number of seconds specified, in which no SSL activity has occurred, the SSL 
connection is refreshed with new session keys. A smaller value can help increase 
security, but has a small impact on performance. The default SSL timeout value is 
43200 seconds. For example: 

value = 100; 

1dap_set_option( ld, LDAP_0PT_SSL_TIME0UT, &value ); 

1dap_get_option( ld, LDAP_0PT_SSL_TIME0UT, &value) 


Note: If you use LDAP_OPT_SSL_TIMEOUT and you are not running on an SSL 
version of IBM Directory Server, an error is returned. 

LDAP_OPT_REBIND_FN: Specifies the address of a routine to be called by the 
LDAP library to authenticate a connection with another LDAP Server when 
chasing a referral or search reference. If a routine is not defined, referrals are 
chased using the identity and credentials specified on the bind sent to the original 
Server. A default routine is not defined. For example: 

extern LDAPRebindProc proc_address; 

LDAPRebindProc value; 

ldap_set_option( ld, LDAP_OPT_REBIND_FN, &proc_address); 
ldap_get_option( ld, LDAP_OPT_REBIND_FN, &value); 

LDAP_OPT_PROTOCOL_VERSION: Specifies the LDAP protocol to be used by 
the LDAP dient library when connecting to an LDAP Server. Also used to 
determine which LDAP protocol is being used for the connection. For an 
application that uses ldap_init() to create the LDAP connection, the default value 
of this Option is LDAP_VERSION3 for communicating with the LDAP Server. The 
default value of this Option is LDAP_VERSION2 if the application uses the 
deprecated ldap_open() API. In either case, the LDAP_OPT_PROTOCOL_VERSION 
Option can be used with ldap_set_option() to change the default. The LDAP 
protocol version must be reset prior to issuing the bind (or any Operation that 
causes an implicit bind). For example: 

version2 = LDAP_VERSI0N2; 
version3 = LDAP_VERSI0N3; 

/* Example for Version 3 application setting version to version 2 */ 

1 dap_set_option( ld, LDAP_0PT_PR0T0C0L_VERSI0N, &version2); 

/* Example of Version 2 application setting version to version 3 */ 

1dap_set_option( ld, LDAP_0PT_PR0T0C0L_VERSI0N, &version3); 

1dap_get_option( ld, LDAP_0PT_PR0T0C0L_VERSI0N, &value); 

LDAP_OPT_SERVER_CONTROLS: Specifies a default list of Server Controls to 
be sent with each request. The default list can be overridden by specifying a Server 
control, or list of Server Controls, on specific APIs. By default, there are no settings 
for Server Controls. For example: 

1dap_set_option( ld, LDAP_0PT_SERVER_C0NTR0LS, &ctrlp); 

LDAP_OPT_CLIENT_CONTROLS: Specifies a default list of dient Controls to be 
processed by the dient library with each request. Because dient Controls are not 
defined for this version of the library, the ldap_set_option() API can be used to 
define a set of default, non-critical dient Controls. If one or more dient Controls in 
the set is critical, the entire list is rejected with a return code of 
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LDAP_UNAVAILABLE_CRITICAL_EXTENS ION 


LDAP_OPT_UTF8_IO: Specifies whether the LDAP library automatically converts 
string data to and from the local code page. It can be set to either 
LDAP_UTF8_XLATE_ON or LDAP_UTF8_XLATE_OFF. By default, the LDAP 
library does not convert string data. 

When conversion is disabled by default, the LDAP library assumes that data 
received from the application using LDAP APIs is already represented in UTF-8. 
Similarly, the LDAP library assumes that the application is prepared to receive 
string data from the LDAP library represented in UTF-8, or as binary 

When LDAP_UTF8_XLATE_ON is set, the LDAP library assumes that string data 
received from the application using LDAP APIs is in the default (or explicitly 
designated) code page. Similarly, all string data returned from the LDAP library 
back to the application is converted to the designated local code page. 

It is important to note that only string data supplied on connection-based APIs is 
translated, that is, only those APIs that include an ld are subject to translation. 

It is also important to note that translation of strings from a UTF-8 encoding to 
local code page can result in loss of data when one or more characters in the 
UTF-8 encoding cannot be represented in the local code page. When this occurs, a 
Substitution character replaces any UTF-8 characters that cannot be converted to 
the local code page. 


For more informa tion on explicitly setting the locale for conversions, see 


ldap_set_locale()| For example: 


int value; 

1dap_set_option( ld, LDAP_0PT_UTF8_I0, (void*)LDAP_UTF8_XLATE_0N); 
1dap_get_option( ld, LDAP_0PT_UTF8_I0, &value); 


LDAP_OPT_HOST_NAME: This is a read-only Option that returns a pointer to 
th e hostname for the original connection (as specified on ldap_init(), ldap_open(). 


or 


ldap_ssl_init() i. For example: 


char *hostname; 

1dap_get_option( ld, LDAP_OPT_HOST_NAME, &hostname); 


Use ldap_memfree to free the memory returned by the call to ldap_get_option(). 


LDAP_OPT_ERROR_NUMBER: This is a read-only Option that returns the error 
code associated with the most recent LDAP error that occurred for the specified 
LDAP connection. For example: 
int error; 

ldap_get_option( ld, LDAP_OPT_ERROR_NUMBER, &error); 


LDAP_OPT_ERROR_STRING: This is a read-only Option that returns the text 
message associated with the most recent LDAP error that occurred for the specified 
LDAP connection. For example: 
char *error_string; 

1dap_get_option( ld, LDAP_OPT_ERROR_STRING, &error_string); 


Use 


ldap_memfree() to free the memory returned by the call to ldap_get_option(). 


LDAP_OPT_API_INFO: This is a read-only Option that returns basic information 
about the API and about the specific implementation being used. The ld parameter 
to ldap_get_option() can be either NULL or a valid LDAP session handle that was 
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obtained by calling ldap_init(), ldap_ssl_init() or ldap_open(). The optdata 
parameter to ldap_get_option() must be the address of an LDAPAPIInfo structure, 
which is defined as follows: 


typedef struct ldapapiinfo { 

int 1dapai_info_version; /* version of this struct (1) */ 

int ldapai_api_version; /* revision of API supported */ 

int ldapai_protocol_version; /* highest LDAP Version supported */ 

char **ldapai_extensions; /* names of API extensions */ 

char *1dapai_vendor_name; /* name of supplier */ 

int ldapai_vendor_version; /* supplier-specific version times 100 */ 
} LDAPAPIInfo; 


Note: The ldapai_info_version field of the LDAPAPIInfo structure must be set to 
the value LDAP_API_INFO_VERSION before calling ldap_get_option() so 
that it can be checked for consistency. All other fields are set by the 
ldap_get_option() function. 


The members of the LDAPAPIInfo structure are: 

ldapai_info_version 

A number that identifies the version of the LDAPAPIInfo structure. This 
must be set to the value LDAP_API_INFO_VERSION before calling 
ldap_get_option(). If the value received is not recognized by the API 
implementation, the ldap_get_option() function sets ldapai_info_version to 
a valid value that can be recognized, sets ldapai_api_version to the correct 
value, and returns an error without filling in any of the other fields in the 
LDAPAPIInfo structure. 

ldapai_api_version 

A number that matches that assigned to the C LDAP API RFC supported 
by the API implementation. This number must match the value of the 
LDAP_API_VERSION dehne. 

ldapai_protocol_version 

The highest LDAP protocol version supported by the implementation. For 
example, if LDAP V3 is the highest version supported then this field is set 
to 3. 


ldapai_extensions 

A NULL-terminated array of character strings that lists the names of API 
extensions. The caller is resp onsible for disposin g of the memory occupied 


by this array by passing it to ldap_value_free() 


LDAP_OPT_EXT_ERROR: This is a read-only Option that returns the extended 
error code. For example, if an SSL error occurred when attempting to invoke an 
ldap_search_s API, the actual SSL error can be obtained by using 
LDAP_OPT_EXT_ERROR: 
int error; 

1dap_get_option( ld, LDAP_OPT_EXT_ERROR, &exterror); 


LDAP_OPT_EXT_ERROR returns errors reported by the SSL library. 


Errors 

If an error occurs, a nonzero return code is returned from ldap_set_option and 
ldap_get_option. 
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LDAP_DEBUG 

To obtain debug information from a dient application built using the IBM 
Directory Server LDAP C-API, you can set the environment variables 
LDAP_DEBUG and LDAP_DEBUG_FILE. 

For UNIX, enter the following command betöre running your application: 
export LDAP_DEBUG=65535 

For the Windows NT and Windows 2000 operating Systems, enter the following 
command betöre running your application: 
set LDAP_DEBUG=65535 

Trace messages in the LDAP C-API library are output to Standard error. Use 
LD AP_DEB UG_FILE =xxxxx to send the trace output to the file xxxxx. 

These environment variables affect only applications run in the same shell (or 
command window) Session. You can also call ldap_set_option() in your application 
to enable and disable the library's trace messages. 

LDAP_SET_OPTION syntax for LDAP V2 applications 

To maintain compatibility with older versions of the LDAP dient library 
(pre-LDAP V3), the ldap_set_option() API expects the value of the following Option 
values to be supplied, instead of the address of the value, when the application is 
running as an LDAP V2 application: 

• LDAP_OPT_SIZELIMIT 

• LDAP_OPT_TIMELIMIT 

• LDAP_OPT_SSL_TIMEOUT 

• LDAP_OPT_DEREF 

• LDAP_OPT_DEBUG 

The value returned by ldap_get_option() when LDAP_OPT_PROTOCOL_VERSION 
is specified can be used to determine how parameters must be passed to the 
ldap_set_option() call. The easiest way to work with this compatibility feature is to 
guarantee that calls to ldap_set_option() are all performed while the 
LDAP_OPT_PROTOCOL_VERSION is set to the same value. If this cannot be 
guaranteed by the application, then follow the format of the following example 
when coding the call to ldap_set_option(): 
int sizeLimit= 100; 

int protocolVersion; 

1dap_get_option( ld, LDAP_0PT_PR0T0C0L_VERSI0N, &protocolVersion ); 

if ( protocolVersion == LDAP_VERSI0N2 ) { 

1dap_set_option( ld, LDAP_OPT_SIZELIMIT, (void *)sizeLimit ); 

} eise { /* the protocol version is LDAP_VERSI0N3 */ 

1dap_set_option( ld, LDAP_OPT_SIZELIMIT, &sizeLimit ); 

} 

An LDAP application is typically running as LDAP V2 when it uses ldap_open() to 
create the LDAP connection. An LDAP application is typically running as LDAP 
V3 when it uses ldap_init() to create the LDAP connection. However, it was 
possible with the LDAP V2 API to call ldap_init(), so there can be cases in which 
this is not true. Note that LDAP_OPT_PROTOCOL_VERSION can be used to 
toggle the protocol, in which case the behavior of ldap_set_option() changes. 
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Locating default LDAP Servers 


When the ldap_init(), ldap_open(), or ldap _ssl_init() APIs ar e invoked with an 
LDAP URL of the following forms, the ldap_server_locate() function is used to 
obtain a set of one or more default LDAP Servers: 


1d=ldap_init ("ldap://", ldap_port); /* locate Servers with 

non-secure ports */ 

1d=ldap_ssl_init ("ldaps://", ldap_port); /* locate Servers with 
secure SSL ports */ 


The ldap_server_locate() API provides several options for searching for default 
LDAP Servers. An application using ldap_server_locate() in an explicit fashion can 
control these options. When ldap_server_locate() is used implicitly, as described 
here, the following options are used: 


Security 

If the non-secure LDAP URL is specified (ldap://), Servers with a 
non-secure security type are used as candidate Servers only. If the secure 
LDAP URL is specified, (ldaps://), Servers with a secure security type are 
used as candidate Servers only. 


Source for Server Information 

The ldap_server_locate() API can be used to find default LDAP Server 
Information in either a local configuration file, or published in the Domain 
Name System (DNS). In this case, the default behavior is used. The 
ldap_server_locate() API looks for a local configuration file first, and 
attempts to find one or more LDAP Servers that meet the search criteria 
(security and suffix filter ). If nothing is found, if then searches DNS. See 


ldap_server_conf_save()| for additional information about using a local 


configuration file. 


DNS Domain Name 


When searching the local configuration and DNS, the ldap_server_locate() 


API assumes that your default LDAP Servers are published in your locally 
configured TCP/DNS, for example, ibm.com. 


Service Name and Protocol 

A complete search is performed using ldap for the Service name and tcp 
for the protocol. If no Servers are located, the search is rerun using _ldap 
and _tcp. 


Note: If the default behavior as described here is not appropriate for your 

application, consider using the ldap_serve r_locate() API explicitly, prior to 


invoking the ldap_init() or ldap_ssl_init() 


API. 


Multithreaded applications 

The LDAP dient libraries are generally thread safe. While a multithreaded 
application can safely use the LDAP library on multiple threads within the 
application, there are a few considerations to keep in mind: 

• Using the LDAP connection, that is, the ld, on the thread that is created is a 
good model. This model avoids the possibility of conflicts that can arise if 
multiple threads are concurrently processing the results of an Operation 
submitted on a different thread. 

• An application can be designed to submit requests on one or more threads, with 
results being fetched on different threads. This is also a good model, because it 
avoids the Situation where two threads are attempting to process the results 
associated with a single LDAP connection. 
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The ldap_get_errno() API obtains Information with respect to the most recent 
error that occurred for the specified LDAP connection. It does not retum the 
most recent LDAP error that occurred on the thread on which it is issued. 


• A key consideration is that only a single thread must be performing operations 
on a particular LDAP connection at any one point in time. 

• Note that the locale is applicable to all conversions by the LDAP library within 
the application's address space. The LDAP locale must be set or changed only 
when there is no other LDAP activity occurring within the application on other 
threads. 


Notes 

Do not make any assumptions about the order or location of elements in the 
opaque LDAP structure. 

See also_ 

ldapjbind 


LDAP_MEMFREE 

ldap_memfree 

ldap_ber_free 

ldap_control_free 

ldap_controls_free 

ldap_msgfree 

Purpose 

Free storage allocated by the LDAP library. 

Synopsis 

#include <ldap.h> 


voi d 

voi d 

voi d 

voi d 

int 1 


1dap_memfree( 


char 

*mem) 

ldap_ber_free( 


BerElement 

*berptr) 

1dap_control_free ( 


LDAPControl 

*ctrl) 

1dap_control s_free) 


LDAPControl 

**ctrl s) 

dap_msgfree( 


LDAPMessage 

*msg) 


Input Parameters 

mem Specifies the address of storage that was allocated by the LDAP library. 

berptr Specifies the address of the BerElement returned from ldap_first_attribute() 
and ldap_next_attribute(). 

Ctrl Specifies the address of an LDAPControl structure. 
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ctrls Specifies the address of an LDAPControl list, represented as a 
NULL-terminated array of pointers to LDAPControl structures. 


Usage 

The ldap_memfree() API is used to free storage that has been allocated by the 
LDAP library (libldap). Use this routine as directed when using ldap_get_option(), 
ldap_first_attribute(), ldap_default_dn_get() and ldap_enetwork_domain_get(). 

The ldap_ber_free() API is used to free the BerElement pointed to by berptr. The 
LDAP library automatically frees the BerElement when ldap_next_attribute() 
returns NULL. The application is responsible for freeing the BerElement if it does 
not invoke ldap_next_attribute() until it returns NULL. 

For those LDAP APIs that allocate an LDAPControl structure, the 
ldap_control_free() API can be used. 

For those LDAP APIs that allocate an array of LDAPControl structures, the 
ldap_controls_free() API can be used. 

The ldap_msgfree() routine is used to free the memory allocated for an LDAP 
message by ldap_result, ldap_search_s, ldap_search_ext_s(), or ldap_search_st(). It 
takes a pointer to the result to be freed and returns the type of the message it 
freed. 

See also 

ldap_controls 


LDAP_MESSAGE 

ldap_first_message 

ldap_next_message 

ldap_count_messages 

Purpose 

Steps through the list of messages of a result chain, as returned by ldap_result(). 

Synopsis 

linclude <ldap.h> 


LDAPMessage *ldap first message! 

LDAP *1d, 

LDAPMessage *result) 

LDAPMessage *ldap next messaget 

LDAP *1d, 

LDAPMessage *msg) 

int 1dap_count_messages( 

LDAP *1d, 

LDAPMessage *result) 


Input Parameters 


ld 


Specifies the L D AP pointer ret urned by a previous call to |ldap_init() 


ldap_ssl_init()| or |ldap_open() 
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result Specifies the result returned by a call to ldap_result() or one of the 
synchronous search routines (ldap_search_s(), ldap_search_st(), or 
ldap_search_ext_s()). 

msg Specifies the message returned by a previous call to ldap_first_message() or 
ldap_next_message(). 


Usage 


These routi nes are used to step through the list of messages in a result chain, as 


returned by ldap_result() 


For search operations, the result chain can include: 

• Referral messages 

• Entry messages 

• Result messages 


The ldap count mes sagesQ API is used to count the number of messages returned. 
The ldap_msgtypeQ API can be used to distinguish between the different message 
types. Unlike ldap_first_entry() ldap_first_message() returns any of the three types 
of messages. 


The ldap_first_message() and ldap_next_message() APIs retum NULL when no 
more messages exist in the result set to be returned. NULL is also returned if an 
error occurs whil e stepping through the entries. When such an error occurs, 
ldap_get_errno() can be used to obtain the error code. 


The ldap_count_messages() API can also be used to count the number of messages 
that remain in a chain if called with a mes sage, entry, or reference returned by 


ldap_first_message(), ldap next_message(), ldap_first_entry() ldap_next_entry() 


ldap_first_reference() and ldap_next_reference() 


Errors 


If an error occurs in ldap_first_message() or ldap_next_message(), the 


ldap_get_ermo()|API can be used to obtain the error code. 


If an error occurs in ldap_count_message s(), -1 is returned, and ldap_g et_ermo() 
can be used to obtain the error code. See 
description of possible error codes. 


'LDAP_ERROR" on page 61 for a 


See also 


ldap result 

ldap first entry 

ldap next entry ldap first reference 

ldap next reference 

ldap get errno 

ldap msgtype 



LDAPJVIODIFY 

ldap_modify 

ldap_modify_ext 

ldap_modify_s 

ldap_modify_ext_s 

ldap_mods_free 

Purpose 

Performs various LDAP modify operations. 
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Synopsis 

linclude <ldap.h> 


typedef struct ldapmod { 
int mod_op; 
char *mod_type; 
union { 

char **modv_strvals; 
struct berval **modv_bvals; 

} mod_vals; 

} LDAPMod; 

#define mod_values mod_vals.modv_strval s 
#define mod bvalues mod vals.modv bvals 


i nt 

dap modify( 



LDAP 

*1 d. 


const char 

*dn. 


LDAPMod 

*mods[]) 

i nt 

dap modify ext( 



LDAP 

*ld. 


const char 

*dn. 


LDAPMod 

*mods[], 


LDAPControl 

**serverctrls 


LDAPControl 

**clientctrls 


i nt 

*msgidp) 

i nt 

dap modify s( 



LDAP 

*1 d. 


const char 

*dn,; 


LDAPMod 

*mods[]) 

i nt 

dap modify ext 

s( 


LDAP 

*1 d. 


const char 

*dn. 


LDAPMod 

*mods[], 


LDAPControl 

**serverctrls 


LDAPControl 

**clientctrls 

voi d 

ldap mods free( 



LDAPMod 

**mods. 


i nt 

*reemods) 

Parameters 


ld 

Specifies the LDAP pointer 


ldap_ssl_init(), or ldap_open() 


dn Specifies the distinguished name (DN) of the entry to be modified. See 


Appendix C, "LDAP distinguished names", on page 179 


for more 


information about DNs. 


mods Specifies a NULL-terminated array of entry modifications. Each element of 
the mods array is a pointer to an LDAPMod structure. 

freemods 

Specifies whether or not the mods pointer is to be freed, in addition to the 
NULL-terminated array of mod structures. 


serverctrls 

Specifies a list of LDAP Server Controls. This parameter can be set to 
NULL. See "LDAP Controls" on page 58 for more information about Server 
Controls. 
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clientctrls 

Spe cifies a list of LDAP dient Co ntrols. This parameter can be set to NULL. 


See "LDAP Controls" on page 58 for more Information about dient Controls. 


Output Parameters 

msgidp 

This result parameter is set to the message ID of the request if the 
ldap_modify_ext() call succeeds. 


Usage 


Th e various modify API s are used to perform an LDAP modify Operation. DN is 


the distinguished name of the entry to modify, and mods is a NULL-terminated 
array of modifications to make to the entry. Each element of the mods array is a 
pointer to an LDAPMod structure. 


The mod_op field is used to specify the type of modification to perform and must 
be one of the following: 

• LDAP_MOD_ADD (0x00) 

• LDAP_MOD_DELETE (0x01) 

• LDAP_MOD_REPLACE (0x02) 


This field also indicates the type of values included in the mod_vals union. For 
binary data, you must also logically OR the Operation type with 
LDAP_MOD_BVALUES (0x 80). This type indicates that the values are specified in 


a NULL-terminated array of 


struct berval 


structures. Otherwise, the mod_values 


are used, that is, the values are assumed to be a NULL-terminated array of 
NULL-terminated character strings. 


The mod_type field specifies the name of the attribute to add, modify or delete. 


The mod_vals field specifies a pointer to a NULL-terminated array of values to 
add, modify, or delete. Only one of the mod_values or modjbvalues variants must 
be used, with modjbvalues being selected by ORing the mod_op field with the 
constant LDAP_MOD_BVALUES. 


The mod_values array is NULL-terminated. Because the ldap_add() API converts 
the string from the local code page to UTF-8, the strings must be in the local code 
page if the LDAP_OPT_UTF8_IO Option has been set to LDAP_UTF8_XLATE_ON 
for the connection. If the UTF-8 translation Option is not set, the array of strings 
must be composed of NULL-terminated UTF-8 strings (note that US-ASCII is a 
proper subset of UTF-8). 

modjbvalues is a NULL-terminated array of berval structures that can be used to 
pass binary values such as images. 

For LDAP_MOD_ADD modifications, the given values are added to the entry, 
creating the attribute if necessary. 

For LDAP_MOD_DELETE modifications, the given values are deleted from the 
entry, removing the attribute if no values remain. If the entire attribute is to be 
deleted, the mod_values field must be set to NULL. 
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For LDAP_MOD_REPLACE modifications, the attribute has the listed values after 
the modification, having been created if necessary, or removed if the mod_vals 
field is NULL. 


All modifications are performed in the Order in which they are listed. 


The ldap_modify_ext() API initiates an asynchronous modify Operation and retums 
the constant LDAP_SUCCESS if the request was successfully sent, or it returns 
another LDAP error code if it is not successful. If successful, ldap mo dify extQ 
places the message ID of the request in *msgidp. A subsequent call to 
can be used to obtain the result of the Operation. When the Operation 


ldap_result() 


nas 


completed, ldap_result() returns the Status of the Operation in the form of an erro r 
code. The error cod e indicates whether the Operation completed successfully. 


ldap_parse_result() 


API checks the error code in the result. 


The 


The ldap_modify() API initiates an asynchronous modify Operation and returns the 
message ID of this Operation. A subsequent call to ldap_result(), can be used to 
obtain the result of the modify. In case of an error, ldap_modify() returns -1, setting 
the session error P arameters in the LDA P structure appropriately, wh ich can be 


obtained by using |ldap_get_errno()[ See 
details. 


/ LDAP_ERROR" on page 61| for more 


The synchronous ldap_modify_ext_s() and ldap_modify_s() APIs both return the 
result of the Operation, either the constant LDAP_SUCCESS if the Operation was 
successful, or another LDAP error code if it was not. 

The ldap_modify_ext() and ldap_modify_ext_s() APIs support LDAP V3 Server 
Controls and dient Controls. 


The ldap_modify_s() API returns the LDA P error code re su lting from the mo dify 


Operation. This code can be interpreted by ldap_perror() or ldap_err2string() 


The ldap_modify() Operation works the same way as ldap_modify_s(), except that 
it is asynchronous, returning the message ID of the request it initiates, or -1 on 
error. The result of the Operation can be obtained by calling ldap_result(). 


ldap_mods_free() can be used to free each element of a NULL-terminated array of 
LDAPMod structures. If freemods is nonzero, the mods pointer is freed as well. 


Errors 

ldap_modify_s() and ldap_modify_ext_s() return the resulting LDAP error code 
from the modify Operation. 


ldap_modify() and ldap_modify_ext() return -1 instead of a valid msgid if an error 
occur s, setting the sessi on e rror in the LD structure, whic h can be obtained by 


using ldap_get_errno() See "LDAP_ERROR" on page 61 for more details. 


See also 


ldap_error ldap_add 


LDAP_PAGED_RESULTS 

ldap_create_page_control 

ldap_parse_page_control 
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Purpose 

Used to request simple paged results of entries returned by the Servers that match 
the filter specified on a search Operation. 


Synopsis 


linclude <ldap.h> 

int 1dap_create_page_control ( 


LDAP 

unsigned long 
struct berval 
const char 
LDAPControl 


*1 d, 

pageSize, 
*cookie, 
isCritical. 
**control) 


int ldap parse page control( 

LDAP *1d, 

LDAPControl **serverControls, 

unsigned long *totalCount, 

struct berval **cookie) 


Input Parameters 

ld Specifies the LDAP pointer returned by previous call to ldap_init(), 
ldap_ssl_init() or ldap_open(). Must not be NULL. 


pageSize 

Number of entries that are returned for this paged results search request. 

cookie Opaque structure returned by the Server. No assumptions must be made 

about the internal Organization or value. The cookie is used on subsequent 
paged results search requests when more entries are to be retrieved from 
the results set. The cookie must be the value of the cookie returned on the 
last response returned from the Server on all subsequent paged results 
search requests. The cookie is empty when there are no more entries to be 
returned by the Server, or when the dient abandons the paged results 
request by sending in a zero page size. After the paged results search 
request is completed, the cookie must not be used because it is no longer 
valid. 


isCritical 

Specifies the criticality of paged results on the search. Whether the 
criticality of paged results is TRUE or FALSE, and the Server finds a 
problem with the sort criteria, the search does not continue. If the Server 
does not find any problem with the paged results criteria, the search 
continues and entries are returned one page at a time. 


serverControls 

A list of LDAP Server Controls. See 


'LDAP Controls" on page 58 for more 


Information about Server Controls. These Controls are returned to the dient 
when calling the ldap_parse_result() function on the set of results returned 
by the Server. 


Output Parameters 

control 

A result parameter that is filled in with an allocated array of one control 
for the sort function. The control must be freed by calling 
ldap_control_free(). 
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totalCount 

Estimate of the total number of entries for this search, can be zero if the 
estimate cannot be provided. 

cookie Opaque structure returned by the Server. No assumptions must be made 

about the internal Organization or value. The cookie is used on subsequent 
paged results search requests when more entries are to be retrieved from 
the results set. The cookie must be the value of the cookie returned on the 
last response returned from the Server on all subsequent paged results 
search requests. The cookie is empty when there are no more entries to be 
returned by the Server, or when the dient abandons the paged results 
request by sending in a zero page size. Once the paged results search 
request is completed, the cookie must not be used because it is no longer 
valid. 


Usage 

The ldap_create_page_control() function uses the page size and the cookie to build 
the paged results control. The control output from ldap_create_page_control() 
function includes the criticality set based on the value of the isCritical flag. This 
control is added to the list of dient Controls sent to the Server on the LDAP search 
request. 

When a paged results control is returned by the Server, the 
ldap_parse_page_control() function can be used to retrieve the values from the 
control. The function takes as input the Server Controls returned by the Server, and 
returns a cookie to be used on the next paged results request for this search 
Operation. 

Note: If the page size is greater than or equal to the search sizeLimit value , the 
Server ignores the paged results control because the request can be satisfied 
in a single page. No paged results control value is returned by the Server in 
this case. In all other cases, error or not, the Server returns a paged results 
control to the dient. 

Simple paged results of search results 

Simple Paged Results provides paging capabilities for LDAP clients that want to 
receive just a subset of search results (page) instead of the entire list. The next page 
of entries is returned to the dient application for each subsequent paged results 
search request submitted by the dient until the Operation is canceled or the last 
result is returned. The Server ignores a simple paged results request if the page 
size is greater than or equal to the sizeLimit value for the Server because the 
request can be satisfied in a single Operation. 

The ldap_create_page_control() API takes as input a page size and a cookie, and 
Outputs an LDAPControl structure that can be added to the list of dient Controls 
sent to the Server on the LDAP search request. The page size specifies how many 
search results must be returned for this request, and the cookie is an opaque 
structure returned by the Server. (On the initial paged results search request, the 
cookie must be a zero-length string). No assumptions must be made about the 
internal Organization or value of the cookie. The cookie is used on subsequent 
paged results search requests when more entries are to be retrieved from the 
results set. The cookie must be the value of the cookie returned on the last 
response returned from the Server on all subsequent paged results search requests. 
The cookie is empty when there are no more entries to be returned by the Server, 
or when the dient application abandons the paged results request by sending in a 
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zero page size. After the paged results search request has been completed, the 
cookie must not be used because it is no longer valid. 

The LDAPControl structure returned by ldap_create_page_control() can be used as 
input to ldap_search_ext() or ldap_search_ext_s(), which are used to make the 
actual search request. 

Note: Server side simple paged results is an optional extension of the LDAP v3 
protocol, so the Server you have bound to prior to the ldap_search_ext() or 
ldap_search_ext_s() call might not support this function. 

Upon completion of the search request you submitted using ldap_search_ext() or 
ldap_search_ext_s(), the Server retums an LDAP result message that includes a 
paged results control. The dient application can parse this control using 
ldap_parse_page_control(), which takes the returned Server response Controls (a 
null terminated array of pointers to LDAPControl structures) as input. 
ldap_parse_page_control() Outputs a cookie and the total number of entries in the 
entire search result set. Servers that cannot provide an estimate for the total 
number of entries might set this value to zero. Use ldap_controls_free() to free the 
memory used by the dient application to hold the Server Controls when you are 
finished processing all Controls returned by the Server for this search request. 

The Server might limit the number of outstanding paged results operations from a 
given dient or for all clients. A Server with a limit on the number of outstanding 
paged results requests might return either LDAP_UNWILLING_TO_PERFORM in 
the sortResultsDone message or age out an older paged results request. There is no 
guarantee to the dient application that the results of a search query have remained 
unchanged throughout the life of a set of paged results request/response 
sequences. If the result set for that query has changed since the initial search 
request specifying paged results, the dient application might not receive all the 
entries matching the given search criteria. When chasing referrals, the dient 
application must send in an initial paged results request, with the cookie set to 
null, to each of the referral Servers. It is up to the application using the client's 
Services to decide whether or not to set the criticality as to the support of paged 
results, and to handle a lack of support of this control on referral Servers as 
appropriate, based on the application. Additionally, the LDAP Server does not 
ensure that the referral Server supports the paged results control. Multiple lists can 
be returned to the dient application, some not paged. It is the dient application's 
decision as to how best to present this information to the end user. Possible 
Solutions include: 

• Combine all referral results betöre presenting to the end user 

• Show multiple lists and the corresponding referral Server host name 

• Take no extra steps and show all results to the end user as they are returned 
from the Server 

The dient application must tum off referrals to get one truly paged list; otherwise, 
when chasing referrals with the paged results search control specified, 
unpredictable results might occur. 

More information about the simple paged results search control, with control OID 
of 1.2.840.113556.1.4.319, can be found in RFC 2686 - LDAP Control Extension for 
Simple Paged Results Manipulation. 
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Errors 


The sort r outines return an LDAP error code if they encounter an error parsing the 
result. See "LDAP_ERROR" on page 61 for a list of the LDAP error codes. 


Notes 

Controls, serverControls, and cookie must be freed by the caller. 

See also 


ldap_search ldap_parse_result 


LDAP_PARSE_RESULT 

ldap_parse_result 

ldap_parse_sasl_bind_result 

ldap_parse_extended_result 

Purpose 

LDAP routines for extracting information from results returned by other LDAP API 
routines. 


Synopsis 

linclude <ldap.h> 


int 1dap_parse_resul t( 


i nt 


i nt 


LDAP 

*ld; 

LDAPMessage 

*res. 

int 

*errcodep. 

char 

**matcheddnp. 

char 

**errmsgp. 

char 

***referralsp. 

LDAPControl 

***servctrlsp. 

int 

freeit) 

ip parse sasl 

bind result( 

LDAP 

*ld; 

LDAPMessage 

*res. 

struct berval 

**servercredp. 

int 

freeit) 

äp_parse_extended_resul t( 

LDAP 

*ld, 

LDAPMessage 

*res. 

char 

**resultoi dp. 

struct berval 

**resultdatap. 

int 

freeit) 


Input Parameters 

ld Specifies the L D AP pointer ret urned by a previous call to ldap_init() 


ldap_ssl_init(). or ldap_open() 


res 


Specifies the result of an LDAP Operation as returned by ldap_result() 
one of the svnchronous LDAP API Operation calls. 


or 


errcodep 

Specifies a pointer to the result parameter that is filled in with the LDAP 
error code field from the LDAPMessage message. The LDAPResult 
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message is produced by the LDAP Server, and indicates the outcome of the 
Operation. NULL can be specified for errcodep if the LDAPResult message 
is to be ignored. 

matcheddnp 

Specifies a pointer to a result parameter. When LDAP_NO_SUCH_OBJECT 
is returned as the LD AP error code, this result parameter is filled in with a 


Distinguished Name indicatmg how much of the name in the request was 


recognized by the Server. NULL can be specified for matcheddnp if the 
match ed DN is to be ig nored. The matched DN string must be freed by 


calling ldap_memfree() 


errmsgp 


Specifies a pointer to a result parameter that is filled in with the contents 
of the error message from the LDAPMessage m essage. The error message 


string must be freed by calling ldap_memfree() 


referralsp 

Specifies a pointer to a result parameter that is filled in with the contents 
of the referrals field from the LDAPMessage message, indicating zero or 
more altemate LDAP Servers where the request must be r etried. The 
referrals array must be freed by calling ldap_value_free() NULL can be 
supplied for this parameter to ignore the referrals field. 

resultoidp 

This result parameter specifies a pointer that is set to point to an allocated, 
dotted-OID text strin g returned from t he Server. This string must be 
disposed of using the ldap_memfree() API. If no OID is returned, 
^resultoidp is set to NULL. 

resultdatap 

This result parameter specifies a pointer to a berval structure poin ter tha t 


is set t o an allocated copy of the data returned by the Server. This 


struct 


berval must be disposed of using ber_bvfree(). If no data is returned, 
^resultdatap is set to NULL. 

serverctrlsp 

Specifies a pointer to a result parameter that is filled in with an allocated 
array of Control s copied out of LDAP Message. The control array must be 


freed by calling ldap_controls_free() 


freeit 


Specifies a Boolean value that determines if the LDAP result (as specified 
by res) is to be freed. Any nonzero val ue results in res being freed after the 
requested information is extracted. The ldap_msgfree() API can be used to 
free the result at a later time. 

servercredp 

Specifies a pointer to a result parameter. For SASL bind results, this result 
parameter is filled in with the credentials returned by the Server for 
mutual authe ntication, if the credent ials are returned. The credentials are 


returned in a 
this field. 


struct berval structure 


NULL might be supplied to ignore 


err 


Specifies an LDAP error code, used as input to ldap_err2string(), so that a 
text description of the error can be obtained. 


Usage 

The ldap_parse_result() API is used to: 

• Obtain the LDAP error code field associated with an LDAPMessage message. 
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• Obtain the portion of the DN that the Server recognizes for a failed Operation. 

• Obtain the text error message associated with the error code returned in an 
LDAPMessage message. 

• Obtain the list of altemate Servers from the referrals field. 

• Obtain the array of Controls that can be returned by the Server. 


The ldap_parse_sasl_bind_result() API is used to obtain Server credentials, as a 
result of an attempt to perform mutual authentication. 


Both the ldap_parse_sasl_bind_result() and the ldap_parse_extended_result() APIs 
ignore messages of type LDAP_RES_SEARCH_ENTRY and 
LDAP_RES_SEARCH_REFERENCE when looking for a result message to parse. 
They both return LDAP_SUCCESS if the result was successfully located and 
parsed, and an LDAP error code if the result was not successfully parsed. 


The |ldap_err2string()| API is used to convert the numeric LDAP error code, as 
returned by any of the LDAP APIs, into a NULL-terminated character string that 
describes the error. The character string is returned as static data and must not be 
freed by the application. 


Errors 

The parse routines return an LDAP error code if they encounter an error parsing 
the result. 


See |"LDAP_ERROR" on page 61 for a list of the LDAP error codes. 

See also 


ldap_error ldap_result 


LDAP_PASSWORD_POLICY 

ldap_parse_pwdpolicy_reponse 

ldap_pwdpolicy_err2string 


Purpose 

LDAP routines for extracting information from results returned in the Password 

Policy Control Structure. 

Synopsis 

linclude <ldap.h> 

int 1dap_parse_pwdpolicy_responset(LDAPCONTROL **serverControls, 
int *controlerr, 
int *controlwarn, 
int *controlres) 

char *ldap_pwdpolicy_err2string(int err); 

Input Parameters 

serverControls 

Specifies an array of LDAPCONTROL pointers returned by a previous call 
to ldap_parse_result(). 
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controlerr 

Specifies a pointer to the result parameter that is filled in with the LDAP 
Password Policy error code, which can be used as input to 
ldap_pwdpolicy_err2string(), so that a text description of the error can be 
obtained. 

controlwarn 

Specifies a pointer to the result parameter that is filled in with the LDAP 
Password Policy warning code, which can be used as input to 
ldap_pwdpolicy_err2string(), so that a text description of the warning can 
be obtained. 

controlres 

Specifies a pointer to the result parameter that is filled in with the LDAP 
Password Policy warning result value. 

err Specifies an integer value returned from ldap_parse_pwdpolicy_response() 
containing the Password Policy warning or error code. 

Usage 

The ldap_parse_pwdpolicy_response() API is used to: 

• Obtain the LDAP Password Policy error or warning Codes from the Password 
Policy Response Control associated with an LDAPMessage message. 

• Obtain the LDAP Password Policy warning result code from the Password 
Policy Response Control that is associated with the returned Password Policy 
warning code. 

The ldap_pwdpolicy_err2string() API is used to convert the numeric LDAP 
Password Policy error or warning code, as returned by 

ldap_parse_pwdpolicy_response(), into a NULL-terminated character string that 
describes the error or warning. The character string is returned as static data and 
must not be freed by the application. 


Errors 

The ldap_parse_pwdpolicy_response routine returns an LDAP error code if it 
encounters an error parsing the result. 


See "LDAP ERROR" on page 61 for a list of the LDAP error codes. 


See also 

ldap_parse_result 


LDAP_PLUGIN_REGISTRATION 

ldap_register_plugin 

ldap_query_plugin 

ldap_free_query_plugin 

Purpose 

LDAP routines that: 

• Register an LDAP dient plug-in. 

• Obtain information about plug-ins that have been registered by the application, 
as well as plug-ins that are defined in ibmldap.conf. 

• Free the array of plug-in information returned from the ldap_query_plugin() AP 
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Synopsis 

linclude <ldap.h> 


int ldap_register_plugin( 

LDAP_Fi1e_Plugin_Info *plugin_info) 

int 1dap_query_plugin( 

LDAP_Fi1e_Plugin_Info plugin_infop ) 


int ldap_free_query_plugin( 


LDAP_Fi1e_Plugin_Info 

***plugin_infop ) 


typedef struct 1dap_fi1e_plug- 

in_info { 


char *type; 

/* plugin type 

*/ 

char *subtype; 

/* plugin subtype 

*/ 

char *path; 

/* path to plugin library 

*/ 

char Unit; 

/* initialization routine 

*/ 

char *paramlist; 

/* plugin parameter list 

*/ 

} LDAP_Fi1e_Pl ugin_Info; 




Input Parameters 

plugin_info 

A structure that contains information about a specific type of SASL plug-in. 

An instance of the structure contains the following fields: 

type NULL-terminated string that defines the plug-in type. The only 
type currently supported is sasl. 

subtype 

NULL-terminated string that specifies the subtype of the plug-in 
being registered. When type=sasl, the subtype is used to specify 
the SASL mechanism supported by the plug-in. For example, 
fingerprint might be specified for any SASL plug-in that supports 
the fingerprint mechanism. For the cram-md5 mechanism, use 
LDAP_MECHANISM_CRAM_MD5. 

path NULL-terminated string that specifies the path to the plug-in's 
shared library. The plug-in path can be a fully-qualified path 
including file name, or only the file name with or without the file 
extension. If only the file name is supplied, the LDAP library 
attempts to find it using Standard operating System search criteria. 

init NULL-terminated string that specifies the initialization routine for 
the plug-in. If NULL, the name of the initialization routine is 
assumed to be ldap_plugin_init. 

parmlist 

NULL-terminated string that specifies arbitrary parameter 
information that is used by the plug-in. For example, if the plug-in 
needs to access a remote security Server, the host name of the 
remote security Server can be supplied as a value in the parameter 
list. 


plugin_infop 

Specifies the address that points to a NULL-terminated array of 
LDAP_Plugin_Info structures. Each LDAP_Plugin_Info structure defined in 
the list contains information about a registered plug-in. For example: 
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LDAP_Fi1e_Plugin_Info **plugin_infop; 

rc = ldap_query_plugin (&plugin_infop); 

plugin_infop 

Specifies the address of a NULL-terminated array of plug-in information 
structures to be freed. 

Output Parameters 

plugin_infop 

Upon successful retum from ldap_query_plugin(), plugin_infop points to a 
NULL-terminated array of LDAP_Plugin_Info pointers. If there are no 
plug-ins registered, the plugin_infop data structure is set to NULL and no 
memory is allocated. 


Usage 

Two mechanisms are available for making an LDAP dient plug-in known to the 
LDAP library: 

• The plug-in is defined in the ibmldap.conf file. 

• The plug-in has been explicitly registered by the application, using the 
ldap_register_plugin() API. 

An application can override the definition of a plug-in in the ibmldap.conf file by 
using the ldap_register_plugin() API. A plug-in is uniquely identified by the 
combination of its type and subtype. For example, an application can choose to use 
its own cram-md5 plug-in (as defined in ibmldap.conf) by invoking 
ldap_register_plugin() and defining another shared library with type="sasl" and 
subtype="cram-md5". Note that plug-ins registered with the ldap_register_plugin() 
API are defined for the application. In this example, other applications still use the 
default cram-md5 plug-in. 

Finding the Plug-in library 

When a plug-in is not explicitly registered by the application with the 
ldap_register_plugin() API, the LDAP library must find the appropriate plug-in 
shared library. To find information about the plug-in, the LDAP library must find 
the ibmldap.conf file. Note that the attempt to locate the ibmldap.conf file is made 
on behalf of the application in whichever of the following events occurs first: 

• The ldap_register_plugin() API is invoked. 

• The ldap_sasl_bind_s() API is invoked. 

After the ibmldap.conf file is accessed, all information in the file is stored 
internally for subsequent use. The file is not re-accessed until the application is 
restarted. However, the application can use the ldap_register_plugin() API to add 
additional plug-in definitions, or to override definitions obtained from the 
ibmldap.conf file. 

The ibmldap.conf file: The ibmldap.conf file contains information required to 
load and initialize default plug-ins. It can also include additional plug-in-specific 
configuration information. The following might be defined for each plug-in in the 
ibmldap.conf file: 

• The plug-in type (for example, sasl) 

• The plug-in subtype (for example, mechanism, if type=sasl) 

• The path to the plug-in shared library 

• The plug-in's initialization routine 
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• The user-defined parameter string 


The ibmldap.conf file might contain one or more records, each defining this 
information for a plug-in. Each record takes the following form: 
plugin type subtype path init-routine Parameters 

For example: 

# 


keyword 

type 

subtype 

path 

init Parameters 

plugin 

sasl 

CRAM-MD5 

1dap_plugin_sasl_cram-md5 

1 dap_plugin_init 

plugin 

sasl 

fpauth 

x:\security\fplib 

fpinit parm2 parm3 

plugin 

sasl 

hitech 

hitech1ib 

hitekinit parm5 parmö 


This example defines three plug-ins (CRAM-MD5, fpauth, and hitek), along with 
associated information. 

Note: If the extension is omitted, then an appropriate extension is assumed for the 
platform; for example, .a on the AIX operating System or .dll on a Windows 
operating System. If the fully-qualified path is omitted, Standard operating 
System search rules are applied. 

Lines beginning with a number sign ( # ) are ignored. 

The algorithm used to locate the ibmldap.conf file is platform specific: 

• On a UNIX System, the following search order is used: 

1. Query the environment variable IBMLDAP_CONF for the path to the 
ibmldap.conf file. 

2. Look for the ibmldap.conf file in the /etc directory. 

• On a Windows System, the following search order is used: 

1. Query the environment variable IBMLDAP_CONF for the path to the 
ibmldap.conf file. 

2. Look in the current directory for the ibmldap.conf file. 

3. Look for the ibmldap.conf file in the \etc directory under the LDAP 
installation directory; for example, c:\Program Files\IBM\LDAP\etc. 

If the definition for a SASL plug-in is not available, the LDAP library encodes the 
SASL bind and transmits it directly to the LDAP Server, bypassing the plug-in 
facility. 


Errors 


These routines return an LDAP error code wh en an error is enco untered. To obtain 
a string description of the LDAP error, use the ldap_err2string() API. 


See also_ 

ldap_error 


LDAP_RENAME 

ldap_rename 

ldap_rename_s 

ldap_modrdn 

ldap_modrdn_s 
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Purpose 

Perform an LDAP rename Operation. 

Synopsis 

#include <ldap.h> 


int ldap_rename( 
LDAP 

const char 
const char 
const char 
int 

LDAPControl 

LDAPControl 

int 


*ld, 

*dn, 

*newrdn, 
*newparent, 
deleteoldrdn, 
**serverctrl s, 
**clientctrls, 
*msgidp) 


int 1dap_rename_s( 
LDAP 

const char 
const char 
const char 
i nt 

LDAPControl 

LDAPControl 


*ld, 

*dn, 

*newrdn, 
*newparent, 
deleteoldrdn, 
**serverctrl s, 
**clientctrls) 


int ldap_modrdn( 
LDAP 

const char 
const char 
int 


*1 d, 

*dn, 

*newrdn, 
deleteoldrdn) 


int 1dap_modrdn_s( 
LDAP 

const char 
const char 
int 


*ld, 

*dn, 

*newrdn, 
deleteoldrdn) 


Input Parameters 


ld Specifies the L D AP pointer ret urned by a previous call to ldap_init() 


ldap_ssl_init()[ or |ldap_open() 


dn Specifies the DN of the entry whose DN is to be changed. When specified 
with the ldap_modrdn() and ldap_modrdn_s() APIs, dn specifies the DN of 
the entry whose RDN is to be changed. 


newrdn 

Specifies the new RDN given to the entry. 


newparent 


Note: Only NULL is supported by IBM Tivoli Directory Server Version 5.2. 
Specifies the new parent, or superior entry. If this parameter is NULL, only 
the RDN of the entry is changed. The root DN can be specified by passing 
a zero length string, The newparent parameter is always NULL when 
using version 2 of the LDAP protocol; otherwise the server's behavior is 
undefined. 

deleteoldrdn 

Specifies an integer value. When set to 1, the old RDN value is to be 
deleted from the entry. When set to 0, the old RDN value must be retained 
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as a non-distinguished value. With respect to the ldap_rename() and 
ldap_rename_s() APIs, this parameter has meaning only if newrdn is 
different from the old RDN. 


serverctrls 

Specifies a list of LDAP Server Controls. This parameter can be set to 


NULL. See 
Controls. 


LDAP Controls" on page 58 for more Information about Server 


clientctrls 

Spe cifies a list of LDAP dient Co ntrols. This parameter can be set to NULL. 


See 


'LDAP Controls" on page 58 


for more information about dient Controls. 


Output Parameters 

msgidp 

This result parameter is set to the message ID of the request if the 
ldap_rename() call succeeds. 


Usage 

In LDAP V2, the ldap_modrdn() and ldap_modrdn_s() APIs were used to change 
the name of an LDAP entry. They can be used to change the least significant 
component of a name (the RDN or relative distinguished name) only. LDAP V3 
provides the Modify DN protocol Operation that allows more general name change 
access. The ldap_rename() and ldap_rename_s() routines are used to change the 
name of an entry. 


The ldap_rename() API initiates an asynchronous modify DN Operation and 
returns the constant LDAP_SUCCESS if the request was successfully sent, or 
another LDAP error code if not. If successful, l dap_rename() places the message ID 
of the request in *msgidp. A subsequent call to ldap_result() can be used to obtain 
the result of the Operation. After the Operation has completed, ldap_result() returns 
the Status of the Operation in the form of an error code. The error code indicates 
whether the Operation completed successfully. The ldap_parse_result() API is used 
to check the error code in the result. 


Similarly, the ldap_modrdn() API initiates an asynchronous modify RDN Operation 
and returns the message ID of the Operation. A subsequent call to ldap_result() can 
be used to obtain the result of the modify. In case of error, ldap_modrdn() returns 
-1, setting the Session err or parameters in t he LDAP structure appropriately, which 


can be obtained by using ldap_get_errno() 


The synchronous ldap_rename_s() API returns the result of the Operation, either 
the constant LDAP_SUCCESS if the Operation was successful, or another LDAP 
error code if it was not. 


The ldap_rename() and ldap_rename_s() APIs both support LDAP V3 Server 
Controls and dient Controls. 

The ldap_modrdn() and ldap_modrdn_s() routines perform an LDAP modify RDN 
Operation. They both take dn, the DN of the entry whose RDN is to be changed, 
and newrdn, the new RDN to give to the entry. ldap_modrdn_s() is synchronous, 
returning the LDAP error code indicating the success or failure of the Operation. In 
addition, they both take the deleteoldrdn parameter, which is used as an integer 
value to indicate whether the old RDN values must be deleted from the entry. 
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Errors 


The synchronous version of this routine retums an LDAP error code, either 
LDAP_SUCCESS or an error code if there was an error. The asynch ronous version 


returns -1 in case of an error. If the asynchrono us API is successful, ldap resultQ 
used to obtain the results of the Operation. See 
more details. 


'LDAP_ERROR" on page 61 


for 


is 


See also 


ldap_error ldap_result 


LDAP_RESULT 

ldap_result 

ldap_msgtype 

ldap_msgid 


Purpose 

Wait for the result of an asynchronous LDAP Operation, obtain LDAP message 
types, or obtain the message ID of an LDAP message. 

Synopsis 

finclude <sys/time.h> /* for struct timeval definition */ 
finclude <ldap.h> 


int 


1dap_resul t( 

LDAP 

int 

int 

struct timeval 
LDAPMessage 


*1 d, 
msgid, 
all, 

*timeout, 
**result) 


int 1dap_msgtype( 

LDAPMessage *msg) 

int 1dap_msgid( 

LDAPMessage *msg) 


Input Parameters 


ld 


Specifies the L D AP pointer ret urned by a previous call to ldap_init() 


ldap_ssl_init() or ldap_open() 


msgid Specifies the message ID of the Operation whose results are to be returned. 
The parameter can be set to LDAP_RES_ANY if any result is desired. 


all This parameter has meaning only for search results. For search results, use 
all to specify how many search result messages are returned in a single call 
to ldap_result(). Specify LDAP_MSG_ONE to retrieve one search result 
message at a time. Specify LDAP_MSG_ALL to request that all results of a 
search be received. ldap_result() waits until all results are received before 
returning all results in a single chain. Specify LDAP_MSG_RECEIVED to 
indicate that all results retrieved so far are to be returned in the result 
chain. 


timeout 

Specifies how long in seconds to wait for results to be returned from 
ldap_result, as identified by the supplied msgid. A NULL value causes 
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msg 


ldap_result() to wait until results are available. To poll, the timeout 
parameter is non-NULL, pointing to a zero-valued timeval structure. 


Specifies a pointer to a result, as ret urned from Ida presultQ, 


ldap_search_s() ldap_search_st() or ldap_search_ext() 


Output Parameters 


result 


Contains the result of the asynchronous Operation i dentified bv msgid This 


result is passed to an LDAP parsing routine such as ldap_first_entry() 


If ldap_result() is unsuccessful, i t returns -1 and se ts the appropriate LDAP error, 
which can be retrieved by using ldap_get_errno() If ldap_result() times out, it 
returns 0. If successful, it returns one of the following result types: 


Idefine LDAP_RES_BIND 0x61L 
#define LDAP_RES_SEARCH_ENTRY 0x64L 
#define LDAP_RES_SEARCH_RESULT 0x65L 
Idefine LDAP_RES_MODIFY 0x67L 
Idefine LDAP_RES_ADD 0x69L 
Idefine LDAP_RES_DELETE 0x6bL 
#define LDAP_RES_MODRDN 0x6dL 
#define LDAP_RES_COMPARE 0x6fL 
Idefine LDAP_RES_SEARCH_REFERENCE 0X73L 
Idefine LDAP_RES_EXTENDED 0X78L 
fdefine LDAP_RES_ANY (-1L) 


#define LDAP RES RENAME LDAP RES MODRDN 


Usage 


The ldap_result() routine is used to wait for and return the result of an Operation 
previousl y initiated by one of the LDA P asynchronous Operation routines; for 
example, ldap_search() ldap_modify() and so forth. These routines return a msgid 
that uniquely identifies the request. The msgid can then be used to request the 
result of a specific Operation from ldap_result(). 


The ldap_msgtype() API returns the type of LDAP message, based on the LDAP 
message passed as input using the msg parameter. 


The ldap_msgid() API returns the message ID associated with the LDAP message 
passed as input using the msg parameter. 


Errors 


ldap result0 retu rns 0 if the timeout expires, and -1 if an error occurs. The 


ldap_get_errno() routine can be used to get an error code. 


Notes 


This routine allocates memory for resu lts that it receives. The memory can be 


deallocated by calling ldap_msgfree() 


See also_ 

ldap_search 
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LDAP SEARCH 


ldap_search 

ldap_search_s 

ldap_search_ext 

ldap_search_ext_s 

ldap_search_st 

Purpose 

Perform various LDAP search operations. 

Synopsis 

finclude <sys/time.h> /* for struct timeval definition */ 


finclude <ldap.h> 


int ldap search( 

LDAP 

const char 
int 

const char 

char 

int 

*ld, 

*base, 

scope, 

*fi1ter, 

*attrs[j, 
attrsonly) 

int ldap search ext( 
LDAP 

const char 
int 

const char 

char 

int 

LDAPControl 

LDAPControl 

struct timeval 

int 

int 

*ld, 

*base, 

scope, 

*fi1ter, 

*attrs [], 
attrsonly, 

**serverctrls, 

**clientctrls, 

*timeout, 

sizelimit, 

*msgidp) 

int ldap search s( 
LDAP 

const char 
int 

const char 

char 

int 

LDAPMessage 

*ld, 

*base, 

scope, 

*fi1ter, 

*attrs[], 
attrsonly, 

**res) 


int 1dap_search_ext_s 


LDAP 

const char 
int 

const char 

char 

int 

LDAPControl 
LDAPControl 
struct timeval 
i nt 

LDAPMessage 

*1 d, 

*base, 

scope, 

*fi1ter, 

*attrs[], 
attrsonly, 

**serverctrls, 

**clientctrls, 

*timeout, 

sizelimit, 

**res) 

int ldap search st( 
LDAP 

const char 

*ld, 

*base. 
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int 

const char 

char 

int 

struct timeval 
LDAPMessage 


scope, 

*fi 1 ter, 
*attrs [], 
attrsonly, 
*timeout, 
**res) 


Input Parameters 


ld 


Specifies the L D AP Pointer re turned by a previous call to ldap_init() 
ldap_ssl_init() or ldap_open() 


base Specifies the DN of the entry the search Starts. 


scope Specifies the scope of the search. It can be LDAP_SCOPE_BASE (to search 
the object itself), or LDAP_SCOPE_ONELEVEL (to search the object's 
immediate children), or LDAP_SCOPE_SUBTREE (to search the object and 
all its descendants). 


filter Specifies a string representation of the filter to apply in the search. Simple 
filters can be specified as attributetype=attributevalue. More complex filters 
are specified using a prefix notation according to the following BNF: 

<filter> : :=’ ('<filtercomp>')’ 

<filtercomp> ::= <and>\<or>\<not>\<simple> 

<and> :: = <filterlist> 

<or> :: = ’|’ <filterlist> 

<not> ::= ’P <filter> 

<filterlist> ::= <filter>\<filter><filtertype> 

<simple> <attributetype><filtertype> 

<attributevalue> 

<filtertype> ::= ’=’ | ’~=’ | ’<=’ | ’>=’ 


The '~=' construct is used to specify approximate matching. The 
representation for <attributetype> and <attributevalue > are as described in 


RFC 2252, LDAP V3 Attribute Syntax Definitions" In addition. 


<attributevalue> can be a single * to achieve an attribute existence test, or 
can contain text and asterisks ( * ) interspersed to achieve substring 
matching. 


For example, the filter "(mail=*)" finds any entries that have a mail 
attribute. The filter "(mail=*@student.of.life.edu)" finds any entries that 
have a mail attribute ending in the specified string. To put parentheses in a 


filter, escape them with a backslash ( \ ) character. See "RFC 2254, A String 


Representation of LDAP Search Filters" for a more complete description of 


allowable filters. 


attrs Specifies a NULL-terminated array of character string attribute types to 

return from entries that match filter. If NULL is specified, all attributes are 
returned. 


attrsonly 

Specifies attribute information. The attrsonly parameter must be set to 1 to 
request attribute types only or set to 0 to request both attribute types and 
attribute values. 


sizelimit 

Specifies the maximum number of entries to return. Note that the Server 
can set a lower limit which is enforced at the Server. 


timeout 

The ldap_search_st() API specifies the local search timeout value. The 
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ldap_search_ext() and ldap_search_ext_s() APIs specify both the local 
search timeout value and the Operation time limit that is sent to the Server 
within the search request. 


serverctrls 

Specifies a list of LDAP Server Controls. This parameter can be set to 


NULL. See 
Controls. 


LDAP Controls" on page 58 for more Information about Server 


clientctrls 

Spe cifies a list of LDAP dient Co ntrols. This parameter can be set to NULL. 


See 


'LDAP Controls" on page 58 


for more information about dient Controls. 


Output Parameters 


res 


Contains the result of the asynchronous Operation identified by msgid, or 
returned directly from ldap_search_s() or ldap search ext s(). This result is 


passed to the LDAP parsing routines (see |"LDAP_RESULT" on page 109| ). 


msgidp 

This result parameter is set to the message ID of the request if the 
ldap_search_ext() call succeeds. 


Usage 

These routines are used to perform LDAP search operations. 

The ldap_search_ext() API initiates an asynchronous search Operation and returns 
the constant LDAP_SUCCESS if the request was successfully sent, or another 
LDAP error code if not. 


If successful, ldap_searc h_ext() places the message ID of the request in *msgidp. 
Use a subsequent call to ldap_result() to obtain the results from the search. 


Similar to ldap_search_ext(), the ldap_search() API initiates an asynchronous search 
Operation and returns the message ID of this Operation. If an error occurs, 
ldap_search() retu rns -1, setting the Session error in the LD structure, which can be 
obtained by using ldap_get_ermo() If successful, use a subsequent call to 
ldap_result() to obtain the results from the search. 


The synchronous ldap_search_ext_s(), ldap_search_s(), and ldap_search_st() 
functions all return the result of the Operation: either the constant LDAP_SUCCESS 
if the Operatio n was successful or an LDAP error code if the Operation was not 


successful. See "LDAP_ERROR" on page 61 for more information about possible 


errors and how to interpret them. If any entries are returned from the search, they 
are contained in the res parameter. This parameter is opaque to the caller. Entries, 
attributes, values, and so forth, must be extracted by calling the result parsing 
routin es. The results co ntained in res must be freed when no longer in use by 


calling ldap_msgfree() 


The ldap_search_ext() and ldap_search_ext_s() APIs support LDAP V3 Server 
Controls and dient Controls, and allow varying size and time limits to be easily 
specified for each search Operation. The ldap_search_st() API is identical to 
ldap_search_s(), except that it requires an additional parameter specifying a local 
timeout for the search. 


There are three options in the Session handle ld which potentially can affect how 
the search is performed. They are: 
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LDAP_OPT_SIZELIMIT 

A limit on the number of entries returned from the search. 0 means no 
limit. Note that the value from the Session handle is ignored when using 
the ldap_search_ext() or ldap_search_ext_s() functions. 

LDAP_OPT_TIMELIMIT 

A limit on the number of seconds to spend on the search. Zero means no 
limit. 


Note: The value from the Session handle is ignored when using the 
ldap_search_ext() or ldap_search_ext_s() functions. 

LDAP_OPT_DEREF 

One of LDAP_DEREF_NEVER (0x00), LDAP_DEREF_SEARCHING (0x01), 
LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS (0x03), 
specifying how aliases must be handled during the search. The 
LDAP_DEREF_SEARCHING value means aliases must be dereferenced 
during the search but not when locating the base object of the search. The 
LDAP_DEREF_FINDING value means aliases must be dereferenced when 
locating the base object but not during the search. 


These options are set and queried using the ldap_set_option() 


ldap_get_option() APIs 




Reading an entry 

LDAP does not support a read Operation directly. Instead, this Operation is 
emulated by a search with base set to the DN of the entry to read, scope set to 
LDAP_SCOPE_BASE, and filter set to "(objectclass=*)". The attrs parameter 
optionally contains the list of attributes to return. 


Listing the children of an entry 

LDAP does not support a list Operation directly. Instead, this Operation is emulated 
by a search with base set to the DN of the list entry, scope set to 
LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)". The attrs parameter 
optionally contains the list of attributes to return for each child entry. If only the 
distinguished names of child entries are desired, the attrs parameter must specify a 
NULL-terminated array of one-character strings that has the value dn. 


Errors 

ldap_search_s(), ldap_search_ext_s and ldap_search_st() return the LDAP error 
code from the search Operation. 


ldap_search() and ldap_search_ext() return -1 instead of a valid msgid if an error 
occurs, setting the Session error in t he LD structure. The Session error can be 


obtained by using ldap_get_errno() 


See 


'LDAP_ERROR" on page 61 


for more details. 


Notes 


These routines allocate storage returned by the res parameter. Use ldap_msgfree() 
to free this storage. 


See also 


ldap_result 

ldap_error 

ldap_sort 

ldap_paged_results 
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LDAP_SERVERJNFORMATION IN DNS 

ldap_server_locate 

ldap_server_free_list 

ldap_server_conf_save 


Purpose 

These LDAP APIs are provided to perform the following operations: 

• Use LDAP Server Information published in the Domain Name System (DNS) to 
locate one or more LDAP Servers, and associated Information. Server 
Information is returned as a linked list of Server Information structures. 

• Free all storage associated with a linked list of Server Information structures. 

• Store information about one or more LDAP Servers in a local configuration 
repository. The local configuration can be used to mimic information that can 
also be published in DNS. 

Synopsis 

finclude <ldap.h> 


int 1dap_server_locate ( 

LDAPServerRequest *server_request, 
LDAPServerlnfo **server_info_listpp); 

int ldap_server_free_list( 

LDAPServerlnfo *server_info_listp); 

int ldap_server_conf_save( 

char *filename, 

unsigned long ttl, 

LDAPServerlnfo *server_info_listp)); 


typedef struct LDAP_Server_Request { 


i nt 

search source; 

/* 

Source for Server info 

*/ 

#define 

LDAP LSI CONF DNS 0 

/* 

Config first, then DNS (def)*/ 

#define 

LDAP LSI CONF ONLV 1 

/* 

Local Config fite only 

*/ 

#define 

LDAP_LSI_DNS_ONLY 2 

/* 

DNS only 

*/ 

char 

*conf_fi1ename 

/* 

pathname of config fite 

*/ 

i nt 

reserved; 

/* 

Reserved, set to zero 

*/ 

char 

*service_key; 

/* 

Service string 

*/ 

char 

*enetwork_domain; 

/* 

eNetwork domain (eDomain) 

*/ 

char 

**name_servers; 

/* 

Array of name Server addrs 

*/ 

char 

**dns_domains; 

/* 

Array of DNS domains 

*/ 

i nt 

connection type; 

/* 

Connection type 

*/ 

#define 

LDAP LSI UDP TCP 0 

/* 

Use UDP, then TCP (default) 

*/ 

#define 

LDAP LSI UDP 1 

/* 

Use UDP only 

*/ 

#define 

LDAP_LSI_TCP 2 

/* 

Use TCP only 

*/ 

i nt 

connection_timeout; 

/* 

connect timeout (seconds) 

*/ 

char 

*DN_fi1ter; 

/* 

DN suffix filter 

*/ 

char 

*proto_key 

/* 

Symbolic protocol name 

*/ 

unsigned char reserved2[60] 

; h 

* reserved fields, set to 0 

*/ 


} LDAPServerRequest; 


typedef struct LDAP Server Info I 

r 


char 

*lsi host; 

/* 

LDAP Server's hostname 

*/ 

unsigned short lsi_port; 

/* 

LDAP port 

*/ 

char 

*1si_suffix; 

/* 

Server's LDAP suffix 

*/ 

char 

*1si_query_key; 

/* 

service_key[.edomai n] 

*/ 

char 

*lsi dns domain; 

/* 

Publishing DNS domain 

*/ 

i nt 

1si_replica_type;/* 

master or replica 

*/ 
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Idefine LDAP_LSI_MASTER 1 /* LDAP Master */ 

Idefine LDAP_LSI_REPLICA 2 /* LDAP Replica */ 

int 1si_sec_type; /* SSL or non-SSL */ 

Idefine LDAP_LSI_NOSSL 1 /* Non-SSL */ 

Idefine LDAP_LSI_SSL 2 /* Secure Server */ 

unsigned short 1si_priority; /* Server priority */ 
unsigned short lsi_weight; /* load balancing weight */ 
char *1si_vendor_info; /* vendor information */ 
char *lsi_info; /* LDAP Info String */ 

struct LDAP_Server_Info *prev; /* linked list previous ptr 
struct LDAP_Server_Info *next; /* linked list next ptr 
} LDAPServerlnfo; 


*/ 

*/ 


Input Parameters 

server_request 

Specifies a pointer to an LDAPServerRequest structure, which must be 
initialized to zero betöre setting specific parameters. This ensures that 
defaults are used when a parameter is not explicitly set. If the default 
behavior is desired for all possible input parameters, simply set 
server_request to NULL. This is equivalent to setting the 
LDAPServerRequest structure to zero. Otherwise, supply the address of the 
LDAPServerRequest structure, containing the following fields: 

search_source 

Specifies where to find the Server information. search_source can 
be one of the following: 

• Access the local LDAP DNS configuration file. If the file is not 
found, or the file does not contain information for a combination 
of the service_key, enetwork_domain and any of the DNS 
domains as specified by the application, then access DNS. 

• Search the local LDAP DNS configuration file only. 

• Search DNS only. 

conf_filename 

Specifies an alternative configuration filename. Specify NULL to 
get the default filename and location. 

service_key 

Specifies the search key, for example, the Service name string to be 
used when obtaining a list of Service records (SRV), pseudo-SRV 
Text records (TXT), or CNAME alias records from DNS. If not 
specified, the default is "ldap." 

Note: Standards are moving towards the use of an underscore ( _ ) 
as a prefix for Service name strings. Over time, it is expected 
that " Jdap" is the preferred Service name string for 
Publishing LDAP Services in DNS. If the application does 
not specify service_key and no entries are returned using the 
default ldap Service name, the search is automatically rerun 
using "_ldap" as the Service name. As an alternative, the 
application can explicitly specify "_ldap" as the Service 
name, and the search is directed specifically at DNS SRV 
records that use "_ldap" as the Service name. 

enetwork_domain 

Indicates that LDAP Servers grouped within the specified 
eNetwork domain are to be located. An eNetwork domain is 
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simply a naming construct, implemented by the LDAP 
administrator, to further subdivide a set of LDAP Servers (as 
published in DNS) into logical groupings. By specifying an 
eNetwork domain, only the LDAP Servers grouped within the 
specified eNetwork domain are returned by the 
ldap_server_locate() API. This can be very useful when 
applications need access to a particular set of LDAP Servers. For 
example, the research division within a Company might use a 
dedicated set of LDAP directories, for example, masters and 
replicas. By Publishing this set of LDAP Servers in DNS with an 
eNetwork domain of research, applications that need access to 
information published in research's LDAP Servers can selectively 
obtain the hostnames and ports of research's LDAP Servers. Other 
LDAP Servers also published in DNS are not returned. 

The criterion for searching DNS to locate the appropriate LDAP 
Servers is constructed by concatenating the following information: 

• service_key (defaults to ldap) 

• enetwork_domain 

• tcp 

• DNS domain 
For example, if: 

• The default service_key of ldap is used 

• The eNetwork domain is sales5 

• The client's default DNS domain is midwest.acme.com 

then the DNS value used to search DNS for the set of LDAP 
Servers belonging to the sales5 eNetwork domain is 
ldap.sales5.tcp.midwest.acme.com. 

If enetwork_domain is set to zero, the following steps are taken to 
determine the enetwork_domain: 

• The locally configured default, if set, is used. 

• If a locally configured default is not set, then a platform-specific 
value is used. On a Windows NT operating System, the user's 
logon domain is used. 

• If a platform-specific eNetwork domain is not defined, then the 
eNetwork domain component in the DNS value is omitted. In 
the above example, this results in the following string being 
used: ldap.midwest.tcp.acme.com. 

If enetwork_domain is set to a NULL string, then the eNetwork 
domain component in the DNS value is omitted. This might be 
useful for finding a default eNetwork domain when a specific 
eNetwork domain is not known. 

Note: If the search is performed with a non-NULL value for 

enetwork_domain, and the search fails, the search is issued 
again with a NULL enetwork_domain, using the specified 
service_key, which defaults to ldap. The second search with 
NULL enetwork_domain is attempted after a complete 
search is concluded without results. For example, if 
search_source is set to the default LDAP_LSI_CONF_DNS, 
then the first search is not considered to be complete until 
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both the local configuration and DNS have been queried. If 
both of these searches fail, then both the local configuration 
and DNS are re-queried with a NULL enetwork_domain. 
The intent is to find a set of LDAP Servers that are 
published under the default Service key, that is, ldap, when 
nothing can be found published under 

ldap.enetwork_domain. The application can determine if the 
located Servers are published in an enetwork_domain by 
examining the lsi_query_key field, as returned in the 
server_info_list structures returned on the 
ldap_server_locate() API. If the returned lsi_query_key 
consists solely of the specified service_key, then the located 
Servers were not published in DNS with the specified 
enetwork_domain. 


name_servers 

Specifies a NULL-terminated array of DNS name Server IP address in 
dotted decimal format, for example, 122.122.33.49. If not specified, the 
locally configured DNS name Servers are used. 

dns_domains 

Specifies a NULL-terminated array of one or more DNS domain names. If 
not specified, the local DNS domain configuration is used. 


Note: The domain names supplied here can take the following forms: 

• austin.ibm.com (Standard DNS format) 

• cn=fred, ou=accounting, dc=austin, dc=ibm, dc=com 


With respect to providing a domain name, these are equivalent. Both result 
in a domain name of austin.ibm.com. This approach makes it easier for an 
application to locate LDAP Servers for bindin g (based on a user na me 
space mapped into the DNS na me space). See 


configuration file" on page 121 


'DNS domains and 


for more information. 


connection_type 

Specifies the type of connection to use when communicating with the DNS 
name Server. The following options are supported: 

• Use UDP first. If no response is received, or data truncation occurs, then 
use TCP. 

• Qnly use UDP. 

• Qnly use TCP. 


If set to zero, the default is to use UDP first (then TCP). 


UDP is the preferred connection type, and typically performs well. You 
might want to consider using TCP/IP if: 

• The amount of data being returned does not fit in the 512-byte UDP 
packet. 

• The transmission and receipt of UDP packets turns out to be unreliable. 
This might depend on network characteristics. 

connection_timeout 

Specifies a timeout value when querying DNS (for both TCP and UDP). If 
LDAP_LSI_UDP_TCP is specified for connection_type and a response is 
not received in the specified time period for UDP, TCP is attempted. A 
value of zero results in an infinite timeout. When the LDAPServerRequest 
parameter is set to NULL, the default is ten seconds. When passing the 
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LDAPServerRequest parameter, this parameter must be set to a nonzero 
value if an indefinite timeout is not desired. 

DN_filter 

Specifies a Distinguished Name to be used as a filter, for selecting 
candidate LDAP Servers based on the server's suffixes. If the most 
significant portion of the DN is an exact match with a server's suffix (after 
normalizing for case), an LDAPServerlnfo structure is returned for the 
Server /suffix combination. If it doesn't match, an LDAPServerlnfo 
structure is not returned for the Server /suffix combination. 

proto_key 

Specifies the protocol key, for example, tcp or _tcp, to be used when 
obtaining a list of SRV, pseudo-SRV TXT or CNAME alias records from 
DNS. If not specified, the default is tcp. 

Note: Standards are moving towards the use of an underscore ( _ ) as a 
prefix for the protocol. Over time, it is expected that _tcp will 
become the preferred protocol string for publishing LDAP and other 
Services in DNS. If the application does not specify protocol_key and 
no entries are returned using the default tcp protocol key, the search 
is automatically rerun using _tcp as the protocol. As an alternative, 
the application can explicitly specify _tcp as the protocol, and the 
search is directed specifically at DNS SRV records that use _tcp as 
the protocol. 

reserved2 

Represents a reserved area for future function, which must be initialized to 
zero. 

server_info_listpp 

Specifies the address that is set to point to a linked list of LDAPServerlnfo 
structures. Each LDAPServerlnfo structure defined in the list contains 
Server information obtained from either of the following: 

• DNS 

• Local configuration 

filename 

Specifies an alternative configuration file name. Specify NULL to get the 
default file name and location. 

ttl Specifies the time-to-live, in minutes, for Server information saved in the 
configuration file. Set ttl to zero if it is intended to be a permanent 
repository of information. 

When the ldap_server_locate() API is used to access the configuration file 
with search_source set to LDAP_LSI_CONF_ONLY, and the configuration 
file has not been refreshed in ttl minutes, the LDAP_TIMEOUT error code 
is returned. 

When the ldap_server_locate() API is used to access the configuration file 
with search_source set to LDAP_LSI_CONF_DNS, and the configuration 
file has not been refreshed in ttl minutes, then network DNS is accessed to 
obtain Server information. 

server_info_listp 

Specifies the address of a linked list of LDAPServerlnfo structures. This 
linked list might have been returned from the ldap_server_locate() API, or 
might be constructed by the application. 
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Output Parameters 

Returns 0 if successful. If an error is encountered, an appropriate return code as 
defined in the ldap.h file is returned. If successful, the address of a linked list of 
LDAPServerlnfo structures is returned. 


server_info_listpp 

Upon successful return from ldap_server_locate(), Server info listpp points 


to a linked list of LDAPServerlnfo structures. The 
structure contains the following fields: 


LDAPServerlnfo 


lsi_host 

Fully-qualified hostname of the target Server (NULL-terminated 
string). 


lsi_port 

Integer representation of the LDAP server's port. 


lsi_suffix 

String that specifies a supported suffix for the LDAP Server 
(NULL-terminated string). 


lsi_query_key 

Specifies the eNetwork domain to which the LDAP Server belongs, 
prefixed by the Service key. For example, if service key is ldap and 
eNetwork domain is sales, then lsi_query_key is set to ldap.sales. If 
the Server is not associated with an eNetwork domain (as 
published in DNS), then lsi_query_key consists solely of the service 
key value. Also, for example, if the service key is _ldap and the 
eNetwork domain is marketing, then lsi_query_key is set to 
_ldap.marketing. 


lsi_dns_domain 

DNS domain in which the LDAP Server was published. For 
example, the DNS search might have been for 
ldap.sales.tcp.austin.ibm.com, but the resulting Servers have a 
fully-qualified DNS host name of ldap2.raleigh.ibm.com. In this 
example, lsi_host is set to ldap2.raleigh.ibm.com while 
lsi_dns_domain is set to austin.ibm.com. The actual domain in 
which the Server was published might be of interest, particularly 
when multiple DNS domains are configured or supplied as input. 


lsi_replica_type 

Specifies the type of Server, LDAP_LSI_MASTER or 
LDAP_LSI_REPLICA. If set to zero, the type is unknown. 

lsi_sec_type 

Specifies the port's security type, LDAP_LSI_NOSSL or 
LDAP_LSI_SSL. This value is derived from the ldap or ldaps prefix 
in the LDAP URL. If the LDAP URL is not defined, the security 
type is unknown and lsi_sectype is set to zero. 


lsi_priority 

The priority value obtained from the SRV RR (or the pseudo-SRV 
TXT RR). Set to zero if unknown or not available. 


lsi_weight 

The weight value obtained from the SRV RR or the pseudo-SRV 
TXT RR. Set to zero if unknown or not available. 
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lsi_vendor_info 

NULL-terminated string obtained from the ldapvendor TXT RR, if 
defined. It might be used to identify the LDAP Server 
vendor/Version information. 

lsi_info 

NULL-terminated information string obtained from the ldapinfo 
TXT RR, if defined. If not defined, lsi_info is set to NULL. This 
information string can be used by the LDAP or network 
administrator to publish additional information about the target 
LDAP Server. 

prev Points to the previous LDAP_Server_Info element in the linked list. This 
value is NULL if at the top of the list. 

next Points to the next LDAP_Server_Info element in the linked list. This value 
is NULL if at the end of the list. 


Usage 


DNS domains and configuration file 

The local configuration file can contain Server information for combinations of the 
following: 

• Service key (typically set to ldap or _ldap) 

• eNetwork domain 

• DNS domains 

When the application sets search_source to the default LDAP_LSI_CONFIG_DNS, 
the ldap_server_locate() API attempts to find Server information in the 
configuration file for the designated service key, eNetwork domain, and DNS 
domains. 

If the configuration file does not contain information that matches this criteria, the 
locator API searches DNS, using the specified service key, eNetwork domain, and 
DNS domains. For example: 

• The application supplies the following three DNS domains: 

- austin.ibm.com 

- raleigh.ibm.com 

- miami.ibm.com 

Also, the application uses the default service key, that is, ldap, and specifies 
sales for the eNetwork domain. 

• The configuration file contains Server information for austin.ibm.com and 
miami.ibm.com, with the default service key and eNetwork domain of sales. 

• Information is also published in DNS for raleigh.ibm.com, with the default 
service key and eNetwork domain of sales. 

• The search_source parameter is set to LDAP_LSI_CONFIG_DNS, which indicates 
that both the configuration file and DNS are to be used if necessary. 

• The locator API builds a single ordered list of Server entries, with the following: 

- Server entries for the austin.ibm.com DNS domain, as extracted from the 
configuration file. 

- Server entries for the raleigh.ibm.com DNS domain, as obtained from DNS 
over the network. 

- Server entries for the miami.ibm.com DNS domain, as extracted from the 
configuration file. 
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The resulting list of Servers contains all the austin.ibm.com Servers first, followed 
by the raleigh.ibm.com Servers, followed by the miami.ibm.com Servers. Within 
each group of Servers, the entries are sorted by priority and weight. 

API usage 

These routines are used to perform operations related to finding and saving LDAP 
Server information. 

ldap_server_locate() 

The ldap_server_locate() API is used to locate one or more suitable LDAP 
Servers. In general, an application uses the ldap_server_locate() API as 
follows: 

• Betöre connecting to an LDAP Server in the enterprise, use 
ldap_server_locate() to obtain a list of one or more LDAP Servers that 
have been published in DNS or in the local configuration file. Typically, 
an application can simply use the default request settings by passing a 
NULL for the LDAPServerRequest parameter. By default, the API looks 
for Server information in the local configuration file first, then moves on 
to DNS if the local configuration file does not exist or has expired. 

Note: If no Server entries are found, and the application does not specify 
the Service key (which defaults to ldap), then the 
ldap_server_locate() function runs the complete search again, 
using the alternative "_ldap" for the Service key. The results of this 
second search, if any, are returned to the application. 

• After the application has obtained the list of Servers, it must walk the 
list, using the first Server that meets its needs. This maximizes the 
advantage that can be derived from using the priority and weighting 
scheme implemented by the administrator. The application might not 
want to use the first Server in the list for several reasons: 

- The dient needs to specifically connect using SSL or non-SSL. For 
each Server in the list, the application can query the rootDSE to 
determine if the Server supports a secure SSL port. This is the 
preferred approach. Alternatively, the application can walk the list 
until it finds a Server entry with the appropriate security type. Note 
that an LDAP Server might be listening on both an SSL and non-SSL 
port. In this case, the Server has two entries in the Server list: 

- The dient specifically needs to connect to a Master or Replica. 

- The dient needs to connect to a Server that supports a particular 
suffix. 


Note: Specify DN_filter to filter out Servers that do not have a suffix. 
The DN resides under this suffix. To confirm that a Server 
actually supports the suffix, query the server's rootDSE. 


Some other characteristic associated with the desired Server exists, 
perhaps defined in the ldapinfo string. 


After the die nt has selected a Server, it then issues the ldap_init 


or 


ldap_ssl_init API. If the selected Server is unavailable, the application is 


free to move down the list of Servers until either it finds a suitable 
Server it can connect to, or the list is exhausted. 


ldap_server_free_list() 

To free the list of Servers and associated LDAPServerlnfo structures, the 
application must use the ldap_server_free_list() API. The 
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ldap_server_free_list() API frees the linked list of LDAPServerlnfo 
structures and all associated storage as returned from the 
ldap_server_locate() API. 

ldap_server_conf_save() 

The ldap_server_conf_save() API is used to störe Server Information into 
local configuration. The format for specifying the Server information on the 
ldap_server_conf_save() API is identical to the format returned from the 
ldap_server_locate() API. 

The application that writes information into the configuration file can 
specify an optional time-to-live for the information stored in the file. When 
an application uses the locator API to access DNS Server information, the 
configuration file is considered to be stale if: 
date/time_fi1e_last_updated + ttl > current_date/time 

If the application uses the default behavior for using the configuration file, 
it bypasses a stale configuration file and attempts to find all needed 
information from DNS. Otherwise, the ttl must be set to zero (indefinite 
ttl), in which case the information is considered to be good indefinitely. 

Setting a nonzero ttl is most useful when an application or other 
mechanism exists for refreshing the local configuration file on a periodic 
basis. 


Note: Sub-second response time can be expected in many cases, when 
using UDP to query DNS. Since most applications get the Server 
information during initialization, repetitive invocation of the locator 
API is usually unnecessary. 

By default, the configuration file is stored in the following platform-specific 
location: 

UNIX /etc/ldap_server_info.conf 

Windows NT and Windows 2000 

%systemroot% \ system32 \ drivers \ etc \ ldap_server_inf o .conf 

Format of local configuration file: The following is a sample definition for a local 
configuration file that is created with the ldap_server_conf_save() API. It is 
recommended that the file be created with the ldap_server_conf_save() API. 
However, with careful editing, it can also be created and maintained manually. 


Some basic rules for managing this file manually: 

• Comment fields must begin with a number sign ( # ). Comment fields are 
ignored. 

• All parameters are positional. 

• The first non-comment line must contain the time-to-live value for the file. 


##################################################################### 

# Local LDAP DNS configuration file. 

# 


# The following line holds the file's expiration time, which is 

# a UNIX time_t value (time in seconds since January 1, 1970 UTC). 

# A value of 0 indicates that the file will not expire. 

#907979782 

0 


# Each of the following lines in this file represents a known 

# LDAP Server. The lines have the following format: 

# 
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# Service domain host priority weight port replica sec "suffix" 

"vendor info" "general info" 

# 

# where: 

# 

# service= service_key[.eNetwork_domain] 

# 

# domain= DNS domain 

# 

# host= fully qualified DNS name of the LDAP Server host 

# 

# priority= target host with the lowest priority is tried first 

# 

# weight= load balancing method. When multiple hosts have 

# same priority, the host to be contacted first is 

# by the weight value. Set to 0 if load balancing 

# 

# port= The port to use to contact the LDAP Server. 

# 

# replica= Use "1" to indicate Master. 

# "2" to indicate Replica. 

# 

# sec= Use "1" to indicate Non-SSL 

# "2" to indicate SSL. 

# 

# suffix= A suffix on the Server. 

# 

# vendor info= a string that identifies the LDAP Server vendor 

# 

# general info= Any informational text you wish to include. 

# 

Idap austin.ibm.com ldapserverl.austin.ibm.com 1 1 389 1 1 
"ou=users,o=ibm,c=us" "IBM SecureWay" "phoneinfo" 

Idap austin.ibm.com ldapserver2.austin.ibm.com 1 1 389 2 1 

"ou=users,o=ibm,c=us" "IBM SecureWay" "phoneinfo replica" 

Idap.gso austin.ibm.com gso3.austin.ibm.com 1 1 636 1 2 . 

Idap.gso austin.ibm.com gso3.austin.ibm.com 1 1 636 1 2 

"cn=GSO,o=IBM,c=US" 

Idap.gso austin.ibm.com gso3.austin.ibm.com 1 1 636 1 2 
"ou=Austin,o=IBM,c=US" "IBM" "GSO ePersonbase" 

Idap.gso austin.ibm.com gso3.austin.ibm.com 1 1 389 1 1 . 

Idap.gso austin.ibm.com gso3.austin.ibm.com 1 1 389 1 1 

"cn=GSO,o=IBM,c=US" 

Idap.gso austin.ibm.com gso3.austin.ibm.com 1 1 389 1 1 
"ou=Austin,o=IBM,c=US" "IBM" "GSO ePersonbase" 

Idap.sales raleigh.ibm.com saleshostl.raleigh.ibm.com 1 1 389 1 1 
"dc=raleigh,dc=ibm, dc=com" "IBM" "Sales Marketing" 

Idap.sales raleigh.ibm.com saleshost2.raleigh.ibm.com 2 1 389 2 1 
"dc=raleigh,dc=ibm, dc=com" "IBM" "Sales Marketing Replica" 

# 

##################################################################### 


the 

determined 
is not needed. 


The newer form of service keys can also be used in the configuration file. For 
example, the following is an excerpt that uses _ldap as the service key: 

_1dap austin.ibm.com ldapserverl.austin.ibm.com 1 1 389 1 1 
"ou=users,o=ibm,c=us" "IBM SecureWay" "phoneinfo" 

_1dap austin.ibm.com ldapserver2.austin.ibm.com 1 1 389 2 1 
"ou=users,o=ibm,c=us" "IBM SecureWay" "phoneinfo replica" 

_ldap.gso austin.ibm.com gso3.austin.ibm.com 1 1 636 1 2 . 

_ldap.gso austin.ibm.com gso3.austin.ibm.com 1 1 636 1 2 

"cn=GSO,o=IBM,c=US" 

_ldap.gso austin.ibm.com gso3.austin.ibm.com 1 1 636 1 2 
"ou=Austin,o=IBM,c=US" "IBM" "GSO ePersonbase" 

_ldap.gso austin.ibm.com gso3.austin.ibm.com 1 1 389 1 1 "" "" 

_ldap.gso austin.ibm.com gso3.austin.ibm.com 1 1 389 1 1 

"cn=GSO,o=IBM,c=US" 
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_ldap.gso austin.ibm.com gso3.austin.ibm.com 1 1 389 1 1 
"ou=Austin,o=IBM,c=US" "IBM" "GSO ePersonbase" 

_ldap.sales raleigh.ibm.com saleshostl.raleigh.ibm.com 1 1 389 1 1 
"dc=raleigh,dc=ibm,dc=com" "IBM" "Sales Marketing" 

_ldap.sales raleigh.ibm.com saleshost2.raleigh.ibm.com 2 1 389 2 1 
"dc=raleigh,dc=ibm,dc=com" "IBM" "Sales Marketing Replica" 

Publishing LDAP Server information in DNS 

If DNS is used to publish LDAP Server information, the LDAP administrator must 
configure the relevant DNS name Servers with the appropriate SRV and TXT 
records that reflect the LDAP Servers available in the enterprise. 

• If SRV records are supported by the DNS Servers in the enterprise, SRV records 


can be created that identify the LDAP Servers, along with appropriate weighting 
and prior ity settings. For more information on SRV records and how thev are 


used,see 

A. Gulbrandsen, P. Vixie, "A DNS RR for Specifving the Location of 

Services (DNS SRV)", Internet RFC 2782, Troll Technologies, Vixie Enterprises,. 

February, 2000 

which obsoletes RFC 2052. 


• TXT records must be associated with the A record of each LDAP Server. The TXT 
records include the LDAP URL records which specify host name, port, base DN 
and port type, for example, ldap for non-SSL, and ldaps for SSL. 

• If SRV records are not being used, the list of available Servers must be specified 
with a set of TXT records which emulate the SRV RR format. 

The LDAP Server locator API: 

• Provides access to a list of LDAP Servers. By default, the locator API queries a 
local configuration file for the required information. If the file was updated with 
a nonzero time-to-live, and the file has become stale, or the file does not contain 
the required information, the locator API then accesses DNS. By default, the 
local configuration file has no time-to-live, and is considered to be good 
indefinitely. 

Note: The configuration file is designed to hold the same level of information 
per Server that can be obtained from DNS. 

• Gathers data relevant to each of the LDAP Servers from DNS, using three 
sequenced algorithms: 

1. SRV records 

2. Pseudo-SRV records (using TXT records) 

3. A CNAME alias referencing a single host's A record 

The algorithms are attempted in sequence until results are returned for one of 
the algorithms. For example, if no SRV records are found, but pseudo-SRV 
records are found, the list of Servers is built from the pseudo-SRV records. 

• Builds a list of LDAP Servers, with the first Server in the list classified as the 
preferred or default Server. Depending on how DNS is used to publish LDAP 
Servers, the preferred LDAP Server can actually be a reflection of how the 
administrator has organized the LDAP information in DNS. The application has 
access to the additional data that was retrieved from DNS. The additional 
information for each LDAP Server information structure can consist of the 
following: 

- Host name and port 

- eNetwork domain of the Server 

- Fully-qualified DNS domain where the hostname is published 

- Suffix 

- Replication type (master or replica) 
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- Security type (SSL or non-SSL) 

- VendorID 

- Administrator-defined data 

The application can use ldap_server_locate() to obtain a list of one or more LDAP 
Servers that exist in the enterprise, and have been published in either DNS or the 
local configuration file. The additional data might be used by the application to 
select the appropriate Server. For example, the application might need a Server that 
Supports a specific suffix, or might need to specifically access the master for 
update operations. 

As input to the API, the application can supply: 

• A list of one or more DNS name Server IP addresses. The default is to use the 
locally configured list of name Server addresses. Once an active name Server is 
located, it is used for all subsequent processing. 

• The Service key. The default is ldap. The Service key is used to query DNS for 
information specific to the LDAP protocol. For example, when searching for SRV 
records in the austin.ibm.com DNS domain, the search is for 
ldap.tcp.austin.ibm.com with type=SRV. This example assumes the search does 
not include an eNetwork domain component. The application can also specify 
_ldap as the Service key and _tcp for the protocol, in which case the search is for 
_ldap._tcp.austin.ibm.com with type=SRV. 

• The name of the eNetwork domain. The eNetwork domain is typically the name 
used to identify the LDAP user's authentication domain, and to further qualify 
the search for relevant LDAP Servers, as published in the user's DNS domain. 
For example, when searching for SRV records in the austin.ibm.com DNS 
domain, with an eNetwork domain of marketing the search is for 
ldap.marketing.tcp.austin.ibm.com with type=SRV. 

• A list of one or more fully-qualified DNS domain names. The default is to use 
the locally configured domains. 

If multiple domains are supplied, either in the default configuration or explicitly 
supplied by the application, information is gathered from each DNS domain. 

The Server information returned from the locator API is grouped by DNS 
domain. If two domains are supplied, for example, austin.ibm.com and 
raleigh.ibm.com, the entries for LDAP Servers published in the austin.ibm.com 
domain appear first in the list, with the austin.ibm.com Servers sorted by 
priority and weight. Entries for LDAP Servers published in the raleigh.ibm.com 
domain follow the entire set of austin.ibm.com Servers (with the raleigh.ibm.com 
Servers sorted by priority and weight). 

Note: All entries returned by the locator API are associated with a single 
<service_key>.<edomain> combination. 

DNS domain names supplied here can take two forms: 

- austin.ibm.com (Standard DNS format) 

- cn=fred, ou=accounting, dc=austin, dc=ibm, dc=com 

With respect to providing a fully-qualified DNS domain name, these are 
equivalent. Both result in a DNS domain name of austin.ibm.com. This approach 
makes it easier for an application to locate LDAP Servers it needs to bind with, 
based on a user name space mapped into the DNS name space. 

• The connection type (UDP or TCP). 

• A DN for comparison against the suffix defined for each LDAP Server entry. 

This string, if supplied, is used as a filter. Only Server entries that define a suffix 
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that compares with the DN are returned by the locator API. For example, a DN 
of "cn=fred, ou=accounting, o=ibm, c=us" matches the first of the following, but 
not the second: 

- o=ibm, c=us 

- o=tivoli, c=us 

The ability to filter based upon each LDAP server's suffix is supplied as a 
convenience, so the application does not need to step through the list of Servers, 
comparing a DN with each entry's suffix. 

• The application can specify how information in the local configuration file is 
used. The default is to look in the local, configuration file for the desired 
information. If the information is not found, then DNS Servers on the network 
are accessed. The application can specify the following: 

- Look in the configuration file first, then access the network (default). 

- Look in the configuration file only. 

- Access DNS only. 

When using the default configuration file, the application does not need to 
specify the location. Alternatively, the application can provide a pathname to a 
configuration file. 

Note: Information stored in the configuration file takes the same form as 

information obtained from DNS. The difference is that it is saved in the 
file by an application. The file can also be constructed and distributed to 
end-users by the administrator. 

Maximum benefit is obtained when applications can use the defaults for all the 
parameters, thus minimizing application knowledge of the specifics related to 
locating LDAP Servers. 

Using SRV and TXT records: The DNS-lookup routine looks for SRV records 
first. If one or more Servers are found, then the Server information is returned and 
the second algorithm, based on TXT records that emulate SRV records, is not 
invoked. 

The use of SRV records for finding the address of Servers, for a specific protocol 
and domain, is described in RFC 2052, "A DNS RR for Specifying the Location of 
Services (DNS SRV)." Correct use of the SRV RR permits the administrator to 
distribute a Service across multiple hosts within a domain, to move the Service 
from host to host without disruption, as well as to designate certain hosts as 
primary and others as alternates, or backups, by using a priority and weighting 
scheme. 

TXT Stands for text. TXT records are simply strings. BIND versions prior to 4.8.3 
do not support TXT records. To fully implement the technique described in RFC 
2052, the DNS name Servers must use a version of BIND that supports SRV records 
as well as TXT records. A SRV resource record (RR) has the following components, 
as described in RFC 2052: 

Service.proto.name ttl dass SRV priority weight port target 

where: 

Service 

Symbolic name of the desired service. By default, the Service name or 
Service key is ldap. When used to publish Servers that are associated with 
an eNetwork domain, the Service value is derived by concatenating the 
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Service key, for example, ldap, with the eNetwork domain name, for 
example, marketing. In this example, the resulting Service is 
ldap.marketing. 

proto Protocol, typically tcp or udp, or _tcp or _udp. 
name Domain name associated with the RR. 
ttl Time-to-live, Standard DNS meaning. 
dass Standard DNS meaning (for example, IN). 

Priori ty 

Target host with lowest number priority must be attempted first. 

weight 

Load balancing mechanism. When multiple target hosts have the same 
priority, the chance of contacting one of the hosts first must be 
proportional to its weight. Set to 0 if load balancing is not necessary. 

port Port on the target host for the Service. 

target Target host name must have one or more A records associated with it. 


The approach is to use SRV records to define a list of candidate LDAP Servers, and 
to then use TXT records associated with each host's A record to gef additional 
information about each LDAP Server. Three forms of TXT records are understood 
by the LDAP dient DNS lookup routines: 

• The Service TXT record provides a Standard LDAP URL, that is, provides host, 
port and base DN. 

• The ldaptype TXT record identifies whether the LDAP Server is a master or 
replica. 

• The ldapvendor TXT record identifies the vendor. 


1 dap 


A 199.23.45.296 

TXT "servi ce: 1 dap://ldap.ibm.com:389/o=foo,c=us" 

TXT "ldaptype: master" 

TXT "ldapvendor: IBMeNetwork" 

TXT "ldapinfo: ldapver=3, keyx=fastserver" 


The ldapinfo free-form TXT record provides additional information, as defined by 
the LDAP or network administrator. As in the example above, the information can 
be keyword based. The ldapinfo record is available to the application. 


In combination, the name Server might contain the following, which effectively 
publishes the set of LDAP Servers that reside in the marketing eNetwork domain: 


dap.marketing.tcp 

SRV 

0 0 0 

1 dapm 


SRV 

0 0 0 

1dapmsec 


SRV 

0 0 0 

Idapmsuffix 


SRV 

1 1 0 

1daprl 


SRV 

1 2 0 

1dapr2 


SRV 

1 2 0 

1dapr2sec 


SRV 

2 1 2222 ldapr3.raleigh.ibm.com. 

dapm 

A 

199.23.45.296 


TXT 

"service: 

1dap://ldapm.austin.ibm.com:389/o=foo,c=us" 


TXT 

"ldaptype 

: master" 

dapmsec 

A 

199.23.45.296 


TXT 

"service: 

1daps://ldapm.austin.ibm.com:686/o=foo,c=us" 


TXT 

"ldaptype 

: master" 

dapmsuffix 

A 

199.23.45.296 
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1daprl 


1dapr2 


1dapr2sec 


TXT "service:ldaps://ldapm.austin.ibm.com:389/o=moo,c=us" 

TXT "ldaptype: master" 

A 199.23.45.297 

TXT "Service:1dap://1daprl:389/o=foo,c=us" 

TXT "ldaptype: replica" 

A 199.23.45.298 

TXT "Service:1dap://ldapr2:389/o=foo,c=us" 

TXT "ldaptype: replica" 

A 199.23.45.298 

TXT "service:1daps://ldapr2/o=foo,c=us" 

TXT "ldaptype: replica" 

TXT "ldapinfo: ca=verisign, authtype=server" 


ldapr3.raleigh.ibm.com. A 199.23.45.299 


In this example, a DNS search for ibmldap.marketing.tcp.austin.ibm.com with 
type=SRV returns seven SRV records, which represent entries for four hosts. Note 
that an SRV record is needed for each port/suffix combination supported by a 
Server. For example, a Server that Supports an SSL and non-SSL port might have at 
least two SRV records and two corresponding A records that point to the same IP 
address. In this example, the A RR combinations for ldapm/ldapmsec/ldapmsuffix 
and Idapr2/ldapr2sec map to the same host address. 

Note: ldapmsuffix provides an alternate suffix for the 199.23.45.296 host. 

The port specified on the SRV record is ignored if the target host has a TXT record 
containing an LDAP URL. If the URL is specified without a port, the default port 
is used (389 for non-SSL, 686 for SSL). 


Some rules for constructing strings associated with the TXT records: 

• If the string contains white space, the entire string following TXT must be 
enclosed in double quotes. 


If the string contains characters not supported by DNS, for example, the suffix 
might contain characters not supported by DNS, an escape is supported, based 


on the technique desc ribed in "Uniform Resource Locators (URL)", Internet RFC 


1738, December 1994 For example: 


TXT 


"service:1daps://1dapr2/o=foo%f0,c=us" 


permits the x'fO' character to be included in the LDAP URL. 

The algorithm for the use of LDAP Servers is outlined below. The LDAP Servers 
are ordered in the list based on this algorithm. The application has the freedom of 
using the first Server in the list based on priority and weight. If also has the 
freedom to select a different Server, based upon its needs. 

Using pseudo-SRV TXT records: If the SRV algorithm does not return any 
Servers, the secondary algorithm is invoked. Instead of looking for SRV records, 
the lookup routine performs a TXT query using the Service name string supplied 
on ldap_server_locate(), which defaults to ldap.tcp. 

The intent is to emulate the scheme provided with SRV records, but using a search 
for TXT records instead. To duplicate the previous example using TXT records 
instead of SRV records, the following definition is used: 
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ldap.marketing.tcp 


1 dapm 


1dapmsec 


Idapmsuffix 


1daprl 


1dapr2 


1dapr2sec 


TXT 

TXT 

TXT 

TXT 

TXT 

TXT 

TXT 


000 ldapm 

000 1dapmsec 

000 Idapmsuffix 

110 1daprl 

1 2 0 1dapr2 

120 ldapr2sec 

2 1 2222 ldapr3.raleigh.ibm.com. 


A 199.23.45.296 

TXT "service:1dap://ldapm.austin.ibm.com:389/o=foo,c=us" 

TXT "ldaptype: master" 

A 199.23.45.296 

TXT "service:ldaps://ldapm.austin.ibm.com:686/o=foo,c=us" 

TXT "ldaptype: master" 

A 199.23.45.296 

TXT "service:ldaps://ldapm.austin.ibm.com:389/o=moo,c=us" 

TXT "ldaptype: master" 

A 199.23.45.297 

TXT "service:1dap://Idaprl:389/o=foo,c=us" 

TXT "ldaptype: replica" 

A 199.23.45.298 

TXT "service:ldap://ldapr2:389/o=foo,c=us" 

TXT "ldaptype: replica" 

A 199.23.45.298 

TXT "service:1daps://Idapr2/o=foo,c=us" 

TXT "ldaptype: replica" 

TXT "ldapinfo: ca=verisign, authtype=server" 


ldapr3.raleigh.ibm.com. A 199.23.45.299 


The LDAP resolver routine assumes that the default domain is in effect when the 
SRV-type TXT records do not contain fully qualified domain names. 


Note: The pseudo-SRV TXT records, in many cases, can exactly replicate the syntax 
of SRV records, with the exception that SRV is replaced by TXT. This makes 
for consistent parsing of the records by the resolver routines, plus it makes it 
very simple to switch between the two mechanisms when inserting this 
information into the DNS database. However, some versions of DNS require 
data associated with the TXT records to be enclosed in double quotes, as 
follows: 

ldap.marketing.tcp TXT "0 0 0 ldapm" 

TXT "0 0 0 1dapmsec" 


The ldap_server_locate() API handles either format. 


Using a CNAME alias record: It the pseudo-SRV algorithm does not return any 
Servers, the third algorithm is invoked. Instead of looking for TXT records, the 
lookup routine performs a Standard query using the Service name string supplied 
on ldap_server_locate(), which defaults to ldap. 
ldap.marketing.tcp CNAME ldapm 


1 dapm 


A 199.23.45.296 

TXT "service:ldap://ldapm.austin.ibm.com:389/o=foo,c=us" 

TXT "ldaptype: master" 
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If TXT records are not associated with the A record, defaults are assumed for port 
and ldaptype. 


Alternative scheme for Publishing LDAP Server information in 


DNS 

A more recent Internet Engineering Task Force (IETF) draft describes a scheme 
where Service keys and the protocol are prefixed with an undersc ore ( ). See the 


following internet draft for more information on this new scheme: 

A. Gulbrandsen, 

P. Vixie, "A DNS RR for Specifving the Location of Services (DNS SRV)", Internet 


RFC 2052, Troll Technologies, Vixie Enterprises. January 1999. 





When Services are published in DNS using the approach proposed in this IETF 
draft, Service names and protocol are prefixed with an underscore ( _ ). 


For instance, a previous example might be defined as follows: 


1dap.marketing._tcp 


SRV 

0 

0 

0 

1 dapm 

SRV 

0 

0 

0 

1dapmsec 

SRV 

0 

0 

0 

1dapmsuffix 

SRV 

1 

1 

0 

1daprl 

SRV 

1 

2 

0 

1dapr2 

SRV 

1 

2 

0 

1dapr2sec 

SRV 

2 

1 

2222 

ldapr3.raleigh.ibm.com. 


If all LDAP Service information is published within your enterprise this way, the 
application can choose to not specify Service key or protocol, and the 
ldap_server_locate() API first performs its search using ldap and tcp. The search 
does not find any entries, and the API automatically runs the search again using 
_ldap and _tcp for Service key and protocol, which returns the information 
published with the alternative scheme. 

If information is published with both schemes, the application must explicitly 
define the Service key and protocol, to ensure that the desired information is 
returned. 


Errors 

ldap_server_locate(), ldap_server_free_list and ldap_server_conf_save() return the 
LDAP error code resulting from the Operation. 


See "LDAP_ERROR" on page 61 for more details. 


See also 

ldap_error 


LDAP_SSL 

ldap_ssl_client_init 

ldap_ssl_init 

ldap_ssl_start (deprecated) 
ldap_set_cipher 

Purpose 

Routines for initializing the Secure Socket Layer (SSL) function for an LDAP 
application, and creating a secure connection to an LDAP Server. 
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Synopsis 


linclude <ldap.h> 


linclude <ldapssl. h> 

int 

1dap_ssl_ 

cl ient_init ( 


char 

*keyring, 


char 

*keyring_pw. 


i nt 

ssl_timeout. 


i nt 

*pSSLReasonCode) 

LDAP 

*ldap_ss 

l_init( 


char 

*host, 


i nt 

port, 


char 

*name) 

int 

Idap ssl 

Start( 


LDAP 

*ld, 


char 

*keyring, 


char 

*keyring_pw. 


char 

*name) 

int 

Idap set 

cipher( 


LDAP 

*1 d, 


char 

*option) 


Input Parameters 


ld 


Specifies the L D AP pointer re turned by a previous call to ldap_init() 


ldap_ssl_init()| or |ldap_open() 


host Several methods are supported for specifying one or more target LDAP 
Servers, including the following: 


Explicit host list 

Specifies the name of the host the LDAP Server runs on. The host 
parameter can contain a blank-separated list of hosts to connect to, 
and each host might optionally be of the form host :port. If pre sent. 


the :port Overrid es the port p arameter supplied on |ldap_init() 


ldap_ssl_init() or ldap_open( . The following are typical examples: 


ld=ldap_ssl_init ("serverl", ldap_port, name); 

1d=ldap_ssl_init ("server2:636, ldap_port, name); 

1d=ldap_ssl_init ( "serverl:636 server2:2000 server3", 
ldap_port, name); 


Local host 

If the host parameter is NULL, the LDAP Server is assumed to be 
running on the local host. 


Default hosts 

If the host parameter is set to ldaps://, the LDAP library attempts 
to locate one or more default L DAP Servers, with sec ure SSL ports, 

function. The 


using the IBM Directory Server ldap_server_locate() 


port specified on the call is ignored, because ldap_server_locate() 
retums the port. For example, the following two are equivalent: 


1d=ldap_ssl_init ("ldaps://", ldap_port, name); 
ld=ldap_ssl_init (LDAPS_URL_PREFIX, LDAPS_PORT, name); 


Note: ldaps or LDAPS_URL_PREFIX must be used to obtain 

Servers with secure ports. If more than one default Server is 
located, the list is processed in sequence, until an active 
Server is found. 

The LDAP URL can include a Distinguished Name, used as a filter 
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for selecting candidate LDAP Servers based on the server's suffixes. 
If the most significant portion of the DN is an exact match with a 
server's suffix after normalizing for case, the Server is added to the 
list of candidate Servers. For example, the following returns default 
LDAP Servers that have a suffix that supports the specified DN 
only: 

1d=ldap_ssl_init ("ldaps:///cn=fred, dc=austin, dc=ibm, 
dc=com", LDAPS_PORT, name); 


In this case, a Server that has a suffix of "dc=austin, dc=ibm, 
dc=com" matches. If more than one default Server is located, the 
list is processed in sequence, until an active Server is found. 


If the LDAP URL contains a host name and optional port, the host 
is used to create the connection. No attempt is made to locate the 
default Servers, and the DN, if present, is ignored. For example, the 
following two are equivalent: 

1d=ldap_ssl_init ("ldaps://myserver", LDAPS_PORT, name); 

1d=ldap_ssl_init ("myserver", LDAPS_PORT, name); 


See r'Locating default LDAP Servers" on page 90| for more 
Information about the algorithm used to locate default LDAP 


Servers. 


Host with privileged port 

On platforms that support the rresvport function (typically UNIX 
platforms), if a specified host is prefixed with "privport: / /", then 
the LDAP library uses the rresvport() function to attempt to obtain 
one of the reserved ports (512 through 1023), instead of an 
ephemeral port. The search for a reserved port starts at 1023 and 
stops at 512. If a reserved port cannot be obtained, the function call 
fails. For example: 

1d=ldap_ssl_init ("privport://serverl, ldap_port, name); 

1d=ldap_ssl_init ("privport://server2:1200, ldap_port, 
name); 

1d=ldap_ss1_init ( "privport://serverl:800 server2:20OO 
privport://server3", ldap_port, name); port 

port Specifies the port number to connect to. If you want the default 
IANA-assigned SSL port of 636, specify LDAPS_PORT. 

keyring 

Specifies the name of a key database file (with kdb extension). The key 
database file typically contains one or more certificates of CAs that are 
trusted by the dient. These types of X.509 certificates are also known as 
trusted roots. A key database can also be used to störe the client's private 
keys and associated dient certificates. A private key and associated dient 
certificate are required only if the LDAP Server is configured to require 
dient and Server authentication. If the LDAP Server is configured to 
provide only Server authentication, a private key and dient certificate are 
not required. 

Default keyring and password 

Applications can use the default keyring file, as installed with the 
LDAP support, by specifying NULL pointers for keyring and 
keyring_pw. The default keyring file, that is, ldapkey.kdb, and the 
associated password stash file, that is, ldapkey.sth, are installed in 
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the /lib directory under LDAPHOME, where LDAPHOME is the 
path to the installed LDAP support. LDAPHOME varies by 
operating System platform: 

• AIX - /usr/ldap 

• Solaris - /usr/IBMldapc 

• Windows - c:\Program Files\IBM\LDAP 

Note: This is the default install location. The actual 

LDAPHOME is determined during installation. 

• HP-UX - /usr/IBMldap 

Applications typically use the default keyring file when the LDAP 
Servers used by the applications are configured with X.509 
certificates issued by one of the well-known default CA. A trusted 
root key is the public key and associated Distinguished Name of a 
CA. The following trusted roots are automatically defined in the 
default LDAP key database file (ldapkey.kdb): 

• Integrion Certification Authority Root 

• IBM World Registry v ' Certification Authority 

• Thawte Personal Premium CA 

• Thawte Personal Freeemail CA 

• Thawte Personal Basic CA 

• Thawte Premium Server CA 

• VeriSign Test CA Root Certificate 

• RSA Secure Server Certification Authority 

• VeriSign dass 1 Public Primary Certification Authority 

• VeriSign dass 2 Public Primary Certification Authority 

• VeriSign dass 3 Public Primary Certification Authority 

• VeriSign dass 4 Public Primary Certification Authority 

Note: Each of these certificates are initially set to be trusted. 

If the default keyring file cannot be located, this set of trusted roots 
is also built-in to the LDAP/SSL code, and is used by default. 

By modifying the contents of ldapkey.kdb, as located in 
LDAPHOME \ lib, all LDAP applications that use SSL and specify 
NULL pointers to keyring and keyring_pw use the revised key 
database without change to each application. There are a variety of 
reasons for changing or customizing a keyring file, including: 

• Adding one or more new trusted roots (that is, adding trust for 
additional CAs). 

• Removing trust. For example, your enterprise might obtain all of 
its Server certificates from VeriSign. In this case, it is appropriate 
to mark the VeriSign certificates as trusted only. 

Note: For the default LDAP keyring file to be generally useful to a 
set of applications, it needs to be readable by each of the 
applications. It is not suitable to störe dient certificates with 
private keys in a keyring file that is readable by users other 
than the owner of the private keys. Therefore, it is 
recommended that dient certificates with private keys not be 
stored in the default LDAP keyring file. They must be stored 
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in keyring files that can be accessed by the appropriate user 
only. Care must be taken to ensure that local file System 
permissions are set so that the keyring file and associated 
stash file, if used, are accessible by the appropriate user 
only 

The password defined for the default ldapkey.kdb file is 
ssl_password. Use this password when initially accessing the 
default keyring database with the gsk7ikm utility. This default 
password is also encrypted into the default keyring password stash 
file, ldapkey.sth, located in the same directory as ldapkey.kdb. Use 
the gsk7ikm utility to change the password. 

If keyring is specified, a fully-qualified path and filename is 
recommended. If a filename without a fully-qualified path is 
specified, the LDAP library looks in the current directory for the 
file. The key database file specified here must have been created 
using the gsk7ikm utility. 


For more information on using gsk7ikm to manage the Contents of 


a key database, see |Chapter 4, "Using gsk7IKM", on page 149 


Note: Although still supported, use of the ldap_ssl_start() is 

discouraged, as its use has been deprecated. Any application 
using the ldap_ssl_start() API must use a single key 
database per application process only. 

keyring_pw 

Specifies the password that is used to protect the contents of the 
key database. This password is important, particularly when it 
protects one or more private keys stored in the key database. The 
password is specified when the key database is initially created, 
and can be changed using the gsk7ikm utility. In lieu of specifying 
the password each time the application opens the keyring 
database, the password can be obtained from a password stash file 
that contains an encrypted version of the password. The password 
stash file can be created using the gsk7ikm utility. To obtain the 
password from the password stash file, specify a NULL pointer for 
keyring_pw. It is assumed that the password stash file has the 
same name as the keyring database file, but with an extension of 
.sth instead of .kdb. It is also assumed that the password stash file 
resides in the same directory as the keyring database file. 


Note: The default keyring file (ldapkey.kdb) is initially configured 
to have ssl_password as its password. This password is also 
initially configured in the default password stash file 
(ldapkey.sth). 

name Specifies the name, or label, associated with the dient private 
key/certificate pair in the key database. It is used to uniquely 
identify a private key/certificate pair, as stored in the key database, 
and might be something like: Digital ID for Fred Smith. 

If the LDAP Server is configured to perform Server Authentication, 
a dient certificate is not required and name can be set to NULL. If 
the LDAP Server is configured to perform Client and Server 
Authentication, a dient certificate is required. name can be set to 
NULL if a default certificate/private key pair has been designated 
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as the default. See Chapter 4, "Using gsk7IKM", on page 149 


Similarly, name can be set to NULL if there is a single 
certificate/private key pair in the designated key database. 


ssl_timeout 

Specifies the SSL timeout value in seconds. The timeout value 
Controls the frequency with which the SSL protocol stack 
regenerates Session keys. If ssl_timeout is set to 0, the default value 
SSLV3_CLIENT_TIMEOUT is used. Otherwise, the value supplied 
is used, provided it is less than or equal to 86,400 (number of 
seconds in a day). If ssl_timeout is greater than 86,400, then 
LDAP_PARAM_ERROR is returned. 


pSSLReasonCode 

Specifies a pointer to the SSL Reason Code, which provides 
additional Information in the event that an error occurs during 
initialization of the SSL stack, when ldap_ssl_client_init() is 
invoked. See ldapssl.h for reason codes that can be returned. 


Usage 

The U.S. government's regulations regarding the export of SDKs which provide 
support for encryption continue to evolve. 

The point of control, with respect to available levels of encryption, is now the 
application. 

Any LDAP application that uses the IBM Tivoli Directory Server C-Client SDK 
Version 5.2 with the required level of GSKit 6.0.3 or higher has default access to 
SSL encryption algorithms. 

ldap_ssl_client_init() is used to initialize the SSL protocol stack for an application 
process. Initialization includes establishing access to the specified key database file. 
The ldap_ssl_client_init() API must be invoked once per application process, prior 
to making any other SSL-related LDAP calls, such as ldap_ssl_init(). Once 
ldap_ssl_client_init() has been successfully invoked, any subsequent invocations 
return a return code of LDAP_SSL_ALREADY_INITIALIZED. This also means that 
a particular key database file is effectively bound to an application process. To 
change the key database, the application or one of its processes must be restarted. 


ldap_ssl_environment_init() can be used instead of ldap_ssl_client_init() with the 
advantage of being able to be called more than once in the same process. Each call 
creates a new SSL environment which is utilized for subsequent SSL sessions 
initiated by calling ldap_ssl_init(). These SSL environments persist as long as the 
LDAP sessions that were created using them persist. 


ldap_ssl_init() is the SSL equivalent of ldap_init() It is used to initialize a secure 
SSL session with a Server. 


Note: The Server is not actually contacted until an Operation is performed that 
requires it, allowing various options to be set after initialization. 

After the secure connection is established for the LDAP session, all subsequent 
LDAP messages tha t flow over the s ecure connection are encrypted, including the 


ldap_simple_bind() parameters, until ldap_unbind() 


is invoked. 


ldap_ssl_init() retums a session handle, a pointer to an opaque data structure that 
must be passed to subsequent calls that pertain to the session. These subsequent 
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calls return NULL if the Session cannot actually be established with the Server. Use 
ldap_get_option() to determine why the call failed. 


The LDAP session handle returned by ldap_ssl_init and ldap_init is a pointer to an 
opaque data type representing an LDAP session. The ldap_get_option() and 
ldap set option Q APIs are used to access a nd set a variety of session-wide 


Parameters. See "LDAP INIT" on page 79 


ldap_get_option() and ldap_set_option(). 


for more Information about 


Note: When connecting to an LDAP V2 Server, one of the ldap_simple_bind() or 
ldapJbmdQ calls must be completed before other operations can be 
performed on the session, with the exception of ldap_set/get_option(). The 
LDAP V3 protocol does not require a bind Operation before performing 
other operations. 

Although still supported, the use of the ldap_ssl_start() API is now deprecated. 

The ldap_ssl_client_init() and ldap_ssl_init() APIs must be used instead. The 
ldap_ssl_start() API Starts a secure connection to an LDAP Server using SSL. 
ldap_ssl_start() accepts the ld from an ldap_open() and performs an SSL 
handshake to a Server. ldap_ssl_start() must be invoked after ldap_open() and prior 
to ldap_bind(). Qnce the secure connection is established for the ld, all subsequent 
LDAP messages that flow over the secure connection are encrypted, including the 
ldap_bind() parameters, until ldap_unbind() is invoked. 

The following scenario depicts the recommended calling sequence where the entire 
set of LDAP transactions are protected by using a secure SSL connection, including 
the dn and password that flow on the ldap_simple_bind(): 

rc = 1dap_ssl_client_init (keyfile, keyfile_pw, timeout, 

&reasoncode); 

ld = ldap_ssl_init(ldaphost, ldapport, label ); 

rc = 1dap_set_option( ld, LDAP_OPT_SSL_CIPHER, &ciphers); 

rc = 1dap_simple_bind_s(1d, binddn, passwd); 

...additional LDAP API calls 

rc = ldap_unbind( ld ); 


Note: The sequence of calls for the deprecated APIs is ldap_open/init(), 
ldap_ssl_start(), followed by ldap_bind(). 


The following ciphers are attempted for the SSL handshake by default, in the order 
shown: 

AES_256 
AES_128 
RC4_SHA_US 
RC4_MD5_US 
DES_SHA_US 
3DES_SHA_US 
RC4_MD5_EXP0RT 
RC2 MD5 EXPORT 


See ldap_get/set_option() for more information on setting the ciphers to be used. 


To specify the number of seconds for the SSL session-level timer, use: 
1dap_set_option(1d,LDAP_0PT_SSL_TIMEOUT, &timeout) 


where timeout specifies timeout in seconds. When timeout occurs, SSL again 
establishes the session keys for the session, for increased security. To specify a 
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specific cipher, or set of ciphers, to be used when negotiating with the Server, use 
ldap_set_option() to define a sequence of ciphers. For example, the following 
defines a sequence of three ciphers to be used when negotiating with the Server. 
The first cipher that is found to be in common with the server's list of ciphers is 
used. 


ldap_set_cipher is the same as calling ldap_set_option (ld, 

LDAP_OPT_SSL_CIPHER, Option). Either function checks the validity of the input 
stri ng. The cipher is used whe n the SSL connection is established by ldap_ssl_init(). 


See 


'LDAP_INIT" on page 79 for more information about ldap_set_option. 


Options 


Options are supported f or Controlling the n ature of the secure connection. These 


options are set using the ldap_set_option() 


API. 


1dap_set_option( ld, LDAP_OPT_SSL_CIPHER, 
(void *) LDAP_SSL_3DES_SHA_US 
LDAP_SSL_RC4_MD5_US); 


The following ciphers are defined in ldap.h: 

#define LDAP_SSL_AES_256 "35" 

#define LDAP_SSL_AES_128 "2F" 

#define LDAP_SSL_RC4_SHA_US "05" 

Idefine LDAP_SSL_RC4_MD5_US "04" 

Idefine LDAP_SSL_DES_SHA_US "09" 

#define LDAP_SSL_3DES_SHA_US "0A" 

Idefine LDAP_SSL_RC4_MD5_EX "03" 

Idefine LDAP_SSL_RC2_MD5_EX "06" 


For more information on ldap_set_option, see |"LDAP_INIT" on page 79 


Notes 

ldapssl.h contains return codes that are specific for ldap_ssl_client_init(), 
ldap_ssl_init() and ldap_ssl_start(). 

The SSL versions of these Utilities include RSA Security Inc. Software. 

The ldap_ssl_client_init(), ldap_ssl_init() and ldap_ssl_start() APIs are only 
supported for the versions of the LDAP library that include the SSL component. 

See also 

ldap_init 


LDAP_START_TLS 


ldap_start_tls 

ldap_start_tls_s 


Purpose 

Start a TLS Session. 
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Synopsis 

#include <ldap.h> 

int 1dap_start_tls_s_np ( 

LDAP *1d, 

const char *certificateName) 

Input Parameters 

ld Specifies the LDAP pointer used in the ldap_start_tls_s_np() call. 
certificateName 

Specifies the name of the certificate to use. It's the same as the parameter 
used in the ldap_ssl_environment_init() API and may be NULL. 


Usage 

The ldap_start_tls_s_np() API is used to secure a previously unsecured connection. 
It takes a handle from an existing LDAP connection and the name of the certificate 
to use. If the command is successful, then communication on the connection will 
be secure until either the connection is closed or an ldap_stop_tls_s_np() call is 
made. 

The secure environment must be initialized, either by calling 
ldap_ssl_environment_init or ldap_ssl_client_init, betöre ldap_start_tls_s_np() is 
called. 


Errors 

ldap_start_tls_s_np() returns LDAP_SUCCESS if the call was successful, or an 
LDAP error if the call was unsuccessful. 

If the connection is already secure, either by going against the SSL port or by 
already establishing a TLS Session, then LDAP_OPERATIONS_ERROR is returned. 

If the secure environment has not been initialized through a call to 
ldap_ssl_client_init or ldap_ssl_environment_init, then 
LDAP_TLS_CLIENT_INIT_NOT_CALLED is returned. 

If the TLS handshake with the Server fails, LDAP_TLS_HANDSHAKE_FAILED is 
returned. 

If the Server is not configured to allow TLS, then LDAP_PROTOCOL_ERROR is 
returned. 

See also 

ldap_stop_tls_s_np, ldap_ssl_environment_init, ldap_ssl_client_init 


LDAP_STOP_TLS 

ldap_stop_tls_s_np 

Purpose 

Abandons an LDAP Operation in progress. 
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Synopsis 

linclude <ldap.h> 

int ldap_stop_tls_s_np( 

LDAP *1d) 

Input Parameters 

ld Specifies the LDAP pointer used in the ldap_start_tls_s_np() call. 

Usage 

The ldap_stop_tls_s_np() API is used to end the TLS Session on a connection. 
Note that this call closes the connection to the Server. 


Errors 

ldap_stop_tls_s_np() returns an LDAP error code; LDAP_SUCCESS if the call was 
successful, an LDAP error if the call was unsuccessful. 

See also 

ldap_stop_tls_s_np, ldap_ssl_environment_init, ldap_ssl_client_init 

LDAP_URL 

ldap_is_ldap_url 

ldap_url_parse 

ldap_free_urldesc 

ldap_url_search 

ldap_url_search_s 

ldap_url_search_st 

Purpose 

LDAP Uniform Resource Locator routines. 

Synopsis 

linclude <sys/time.h> /* for struct timeval definition */ 
linclude <ldap.h> 


int 1dap_is_ldap_url ( 

char *url) 

int ldap_url_parse( 

char *url, 

LDAPURLDesc **ludpp) 

typedef struct 1dap_url_desc { 


char 

*1 

1ud_host; 

/* 

LDAP host to contact */ 

int 


1ud_port; 

/* 

port on host */ 

char 

*1 

1ud_dn; 

/* 

base for search */ 

char 

**" 

1ud_attrs; 

/* 

NULL-terminate fist of attributes */ 

int 


1ud_scope; 

/* 

a valid LDAP_SC0PE_... value */ 

char 

*1 

1ud_fi1ter; 

/* 

LDAP search filter */ 

char 

*1 

lud_string; 

/* 

for internal use only */ 


} LDAPURLDesc; 
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ldap_free_urldesc( 

LDAPURLDesc *ludp) 

int ldap_url_search( 


LDAP 

*1 d. 

char 

*url, 

int 

attrsonly) 

dap url search s| 


LDAP 

*1 d. 

char 

*url, 

int 

attrsonly. 

LDAPMessage 

**res) 

dap url search st( 

LDAP 

*1 d. 

char 

*url, 

i nt 

attrsonly. 

struct timeval 

*timeout. 

LDAPMessage 

**res) 


Input Parameters 


ld 


Specifies the L D AP pointer re turned by a previous call to |ldap_init() 


ldap_ssl_init()| or |ldap_open() 


url Specifies a pointer to the URL string. 


attrsonly 

Specifies attribute information. Set to 1 to request attribute types only. Set 
to 0 to request both attribute types and attribute values. 


timeout 

Specifies a timeout value for a svnchronous search issued by the 
ldap_url_search_st() routine. 

ludp Points to the LDAP URL description, as returned by ldap_url_parse(). 

Output Parameters 

ludpp Points to the LDAP URL description, as returned by ldap_url_parse(). 

res Contains the result of the asvnch ronous Operation identified by msgid, as 
returned from ldap_url_search_s() or ldap_url_search_st(). This result must 
be passed to the LDAP parsing routines. 

Usage 

These routines support the use of LDAP URLs. LDAP URLs look like the 
following: 

1dap:// [ hostport]/dn [lattributes [Iscope [?/z lter ]]] 


where: 

• hostport is a host name with an optional :portnumber. 

• dn is the base DN to be used for an LDAP search Operation. 

• attributes is a comma-separated list of attributes to be retrieved. 

• scope is one of the following three strings: base, one, or sub. The default is base. 

• filter is the LDAP search filter as used in a call to ldap_search. 

For example: 

1dap://1dap.itd.umich.edu/c=US?o,description?one?o=umich 
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URLs that are wrapped in angle-brackets or preceded by URL: or both are also 
tolerated, including the following forms: 

• URL:ldapurl 
For example: 

URL:ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich 

• <URL:ldapurl> 

For example: 

<URL:ldap://ldap.itd.umich.edu/c=US?o,descnption?one?o=umich> 


ldap_is_ldap_url() returns a nonzero value if url begins with ldap://. It can be used 
as a quick check for an LDAP URL; the ldap_url_parse() routine is used to extract 
the various components of the URL. 

ldap_url_parse() breaks down an LDAP URL passed in url into its component 
pieces. If successful, zero is returned, an LDAP URL description is allocated and 
filled in, and ludpp is set to point to it. If an error occurs, one of these values is 
returned: 

LDAP_URL_ERR_NOTLDAP - URL doesn't begin with "ldap://" 

LDAP_URL_ERR_NODN - URL has no DN (required) 

LDAP_URL_ERR_BADSCOPE - URL scope String is invalid 
LDAP_URL_ERR_MEM - can't allocate memory space 


ldap_free_urldesc() is called to free an LDAP URL description that was obtained 
from a call to ldap_url_parse(). 

ldap_url_search() initiates an asynchronous LDAP search based on the contents of 
the URL string. This routine acts just like ldap_search except that the search 
Parameters are pulled out of the URL. 


ldap_url_search_s() performs a synchron ous LDAP search based on the contents of 
the URL string. This routine acts just like ldap_search_s() except that the search 
Parameters are pulled out of the URL. 


ldap_url_search_st() performs a sy nchronous LDAP URL search with a specified 
timeout. This routine acts just like ldap_search_st() except that the search 
Parameters are pulled out of the URL. 


Notes 

For search operations, if hostport is omitted, host and port for the current 
connection are used. If hostport is specified, and is different from the host and port 
combination used for the current connection, the search is directed to hostport, 
instead of using the current connection. In this case, the underlying referral 
mechanism is used to bind to hostport. 

If the LDAP URL does not contain a search filter, the filter defaults to 
objectClass=*. 

See also_ 

ldap_search 
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LDAP_SSL_ENVIRONMENT_INIT 

Purpose 

ldap_ssl_environment_init() has the same parameters as ldap_ssl_client_int() but 
can be called more than once. It returns LDAP_SUCCESS or the appropriate LDAP 
error code. It does not return LDAP_SSL_ALREADY_INITIALIZED. An application 
that requires SSL Connections to different Servers can initialize environments in 
separate calls to this function, with different key database files. The environment 
created is used by all SSL connections established by calling ldap_ssl_init() until 
the next call is made to ldap_ssl_environment_init(). Subsequent calls to 
ldap_ssl_environment_init() do not affect existing SSL connections. 

Synopsis 

finclude <ldap.h> 

#include <1dapssl.h> 

int ldap_ssl_environment_init( 


char 

*keydatabase. 

char 

*keydatabase_pw. 

i nt 

ssl_timeout. 

i nt 

*pSSLReasonCode) 

where 



keydatabase 

Specifies the name of a key database file with .kdb extension. The key 
database file typically contains one or more certificates of CAs that are 
trusted by the dient. These types of X.509 certificates are also known as 
trusted roots. A key database can be used to störe the client's private keys 
and associated dient certificates. A private key and associated dient 
certificate are required if the LDAP Server is configured to require dient 
and Server authentication only. If the LDAP Server is configured to provide 
only Server authentication, a private key and dient certificate are not 
required. 

keydatabase_pw 

Specifies the password that is used to protect the contents of the key 
database. This password is important, particularly when it protects one or 
more private keys stored in the key database. The password is specified 
when the key database is initially created, and can be changed using the 
gsk7ikm utility. Instead of specifying the password each time the 
application opens the key database, the password can be obtained from a 
password stash file that contains an encrypted version of the password. 

The password stash file can be created using the gsk7ikm utility. To obtain 
the password from the password stash file, specify a NULL pointer for 
keydatabase_pw. It is assumed that the password stash file has the same 
name as the key database file, but with a .sth extension instead of .kdb. It 
is assumed that the password stash file resides in the same directory as the 
key database file. 

Note: The default key database file, ldapkey.kdb, is initially configured to 
have ssl_password as its password. This password is also initially 
configured in the default password stash file (ldapkey.sth). 

ssl_timeout 

Specifies the SSL timeout value in seconds. The timeout value Controls the 
frequency with which the SSL protocol stack regenerates Session keys. If 
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ssl_timeout is set to 0, a default value is used. Otherwise, the value 
supplied is used, provided it is less than or equal to 86,400, the number of 
seconds in a day. If ssl_timeout is greater than 86,400, 
LDAP_PARAM_ERROR is returned. 

pSSLReasonCode 

Specifies a pointer to the SSL Reason Code, which provides additional 
information in the event that an error occurs during initialization of the 
SSL stack, when ldap_ssl_environment_init() is invoked. See ldapssl.h for 
reason codes that can be returned. 


LDAP_SORT 

ldap_create_sort_keylist 

ldap_free_sort_keylist 

ldap_create_sort_control 

ldap_parse_sort_control 


Purpose 

Used to request sort of entries returned by the Servers that match the filter 
specified on a search Operation. 


Synopsis 

linclude <ldap.h> 

int 1dap_create_sort_keyl ist( 

LDAPsortkey ***sortKeyl_ist, 

const char *sortString); 

int 1dap_create_sort_control( 

LDAP *1d, 

LDAPsortkey **sortKeyList, 

const char isCritical, 

LDAPControl **control) 


void ldap_free_sort_keylist( 

LDAPsortkey **sortKeyList) 


int 1dap_parse_sort_control ( 

LDAP *ld, 

LDAPControl **serverControl s, 

unsigned long *sortRC, 

char **attribute) 


Input Parameters 

ld Specifies the LDAP pointer returned by previous call to ldap_init(), 
ldap_ssl_init() or ldap_open(). Must not be NULL. 

sortString 

String with one or more attributes to be used to sort entries returned by 
the Server. 

sortKeyList 

Pointer to an array of LDAPsortkey structures, which represent attributes 
that the Server uses to sort returned entries. Input when used for 
ldap_create_sort_control() and ldap_free_sort_keylist(). 

isCritical 

Specifies the criticality of sort on the search. If the criticality of sort is 
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FALSE, and the Server finds a problem with the sort criteria, the search 
continues but entries returned are not sorted. If the criticality of sort is 
TRUE, and the Server finds a problem with the sort criteria, the search 
does not continue, no sorting is done, and no entries are returned. If the 
Server does not find any problem with the sort criteria, the search and sort 
continues and entries are returned sorted. 


serverControls 

A list of LDAP Server Controls. See 


'LDAP Controls" on page 58 for more 


Information about Server Controls. These Controls are returned to the dient 
when calling the ldap_parse_result() function on the set of results returned 
by the Server. 


Output parameters 

sortKeyList 

Pointer to an array of LDAPsortkey structures, which represent attributes 
the Server uses to sort returned entries. Output when used for 
ldap_create_sort_keylist(). 

control 

A result parameter that is filled in with an allocated array of one control 
for the sort function. The control must be freed by calling 
ldap_control_free(). 

sortRC 

LDAP return code retrieved from the sort results control returned by the 
Server. 

attribute 

Returned by the Server, this is the name of the attribute in error. 


Usage 

These routines are used to perform sorting of entries returned from the Server 
following an LDAP search Operation. 

The ldap_create_sort_keylist() function builds a list of LDAPsortkey structures 
based on the list of attributes included in the incoming string. A sort key is made 
up of three possible values: 

• Name of attribute used to sort entries returned by the Server 

• OID of a matching rule for that attribute 

• Whether or not the sort must be done in reverse order 

The svntax of the attributes in the sortString, [-]<attribute name>[:<matching rule 
OID>], specifies whether or not there is a matching rule OID that must be used for 
the attribute, and whether or not the attribute must be sorted in reverse order. In 
the following example sortString, the search results are sorted first by surname and 
then by given name, with the given name being sorted in reverse (descending 
order) as specified by the prefixed minus sign ( - ): 
sn -givenname 

Thus, the syntax of the sort parameter is as follows: 

[-]<attribute name>[:<matching rule 01 D>] 

where 

• attri bute name is the name of the attribute you want to sort by. 
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• matching rule OID is the optional OID of a matching rule that you want to use 
for sorting. 

• the minus sign ( -) indicates that the results must be sorted in reverse order. 

The sortKeyList, output from the ldap_create_sort_keylist() function, can be used 
as input into the ldap_create_sort_control() function. The sortKeyList is an ordered 
array of LDAPsortkey structures such that the key with the highest precedence is 
at the front of the array The control output form ldap_create_sort_control() 
function includes the criticality set based on the value of the isCritical flag. This 
control is added to the list of dient Controls sent to the Server on the LDAP search 
request. 

The ldap_free_sort_keylist() function cleans up all the memory used by the sort 
key list. This function must be called after the ldap_create_sort_control() function 
has completed. 

When a sort results control is returned by the Server, the ldap_parse_sort_control() 
function can be used to retrieve the values from the control. The function takes as 
input the Server Controls returned by the Server, and returns the value of the sort 
control return code and possibly an attribute name if the return code is not 
LDAP_SUCCESS. If there was an error parsing the sort criteria for the search or 
there were no entries returned for the search, no sort control is returned to the 
dient. 

Server side sorting of search results 

Sorted Search Results provides sort capabilities for LDAP clients that have limited 
or no sort functionality. Sorted Search Results enables an LDAP dient to receive 
sorted search results based on a list of criteria, where each criteria represents a sort 
key. The sort criteria includes attribute types, matching rules, or descending order. 
The Server must use this criteria to sort search results betöre returning them. This 
moves the responsibility of sorting from the dient application to the Server, where 
it might be done much more efficiently. For example, a dient application might 
want to sort the list of employees at their Grand Cayman site by surname, 
common name, and telephone number. Instead of building the search list twice so 
it can be sorted (once at the Server and then again at the dient when all the results 
are returned), the search list is built once, and then sorted, betöre returning the 
results to the dient application. 

In the following example sortString, the search results are sorted first by surname 
(sn), then by given name (givenname), with the given name being sorted in reverse 
(descending) order as specified by the prefixed minus sign ( - ). 
sn -givenname 

The sortKeyList output from ldap_create_sort_keylist() can be used as input to 
ldap_create_sort_control(). The sortKeyList is an ordered array of LDAPsortkey 
structures such that the key with the highest precedence is at the front of the array. 
ldap_create_sort_control() Outputs a LDAPControl structure which can be added to 
the list of dient Controls sent to the Server on the LDAP search request. The 
LDAPControl structure returned by the ldap_create_sort_control() API can be used 
as input to ldap_search_ext() or ldap_search_ext_s(), which are used to make the 
actual search request. 

Note: Server side sorting is an optional extension of the LDAP v3 protocol, so the 
Server you have bound to prior to the ldap_search_ext() or 
ldap_search_ext_s() call might not support this function. 
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Now that you have created the Server side control, you can free the sortKeyList 
output from ldap_create_sort_keylist() using ldap_free_sort_keylist(). 

Upon completion of the search request you submitted using ldap_search_ext() or 
ldap_search_ext_s(), the Server returns an LDAP result message that includes a sort 
results control. The dient application can parse this control using 
ldap_parse_sort_control() which takes the returned Server response Controls (a null 
terminated array of pointers to LDAPControl structures) as input. 
ldap_parse_sort_control() Outputs a return code that indicates whether or not the 
sort request was successful. If the sort was not successful, the name of the attribute 
in error might be output from ldap_parse_sort_control(). Use ldap_controls_free() 
to free the memory used by the dient application to hold the Server Controls when 
you are done processing all Controls returned by the Server for this search request. 

The Server returns a successful return code of LDAP_SUCCESS in the sort response 
control (sortKeyResponseControl) in the search result (searchResultDone) message 
if the Server supports sorting and can sort the search results using the specified 
keys. If the search fails for any reason or there are no search results, then the 
Server omits the sortKeyResponseControl from the searchResultsDone message. 

If the Server does not support sorting and the criticality specified on the sort 
control for the search request is TRUE, the Server does not return any search 
results, and the sort response control return code is set to 
LDAP_UNAVAILABLE_CRITICAL_EXTENSION. If the Server does not support 
sorting and the criticality specified on the sort control for the search request is 
FALSE, the Server returns all search results and the sort control is ignored. 

If the Server does support sorting and the criticality specified on the sort control 
for the search request is TRUE, but for some reason the Server cannot sort the 
search results, then the sort response control return code is set to 
LDAP_UNAVAILABLE_CRITICAL_EXTENSION and no search results are 
returned. If the Server does support sorting and the criticality specified on the sort 
control for the search request is FALSE, and for some reason the Server cannot sort 
the search results, then the sort response control return code is set to the 
appropriate return code and all search results are returned unsorted. 

The following return codes might be returned by the Server in the 
sortKeyResponseControl of the searchResultDone message: 

• LDAP_SUCCESS - the results are sorted 

• LDAP_OPERATIONS_ERROR - Server internal failure 

• LDAP_TIMELIMIT_EXCEEDED - time limit reached betöre sorting was 
completed 

• LDAP_STRONG_AUTH_REQUIRED - refused to return sorted results using 
insecure protocol 

• LDAP_ADMIN_LIMIT_EXCEEDED - too many matching entries for the Server 
to sort 

• LDAP_NO_SUCH_ATTRIBUTE - unrecognized attribute type in sort key 

• LDAP_INAPPROPRIATE_MATCHING - unrecognized or inappropriate 
matching rule in sort key 

• LDAP_INSUFFICIENT_ACCESS - refused to return sorted results to this dient 

• LDAP_BUSY - too busy to process 

• LDAP_UNWILLING_TO_PERFORM - unable to sort 

• LDAP_OTHER - unable to sort due to reasons other than those specified above 
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There are other rules that must be taken into consideration when requesting sort 

from the Server, These rules include the following: 

• The matching rule must be one that is valid for the sort attribute it applies to. 
The Server returns LDAP_INAPPROPRIATE_MATCHING if it is not. 

• If the matching rule is omitted from a sort key, the ordering matching rule 
defined for use with this sort attribute must be used. 

• A Server can restrict the number of keys supported for a sort control, such as 
supporting only one key (A sort key list of at least one key must be supported). 

• If a search result meets the search criteria but is missing a value for the sort key 
(sort attribute value is NULL), then this search result is considered a larger value 
than any other valid values for that key. 


When sorted search is requested along with simple paged results, the 
sortKeyResponseControl is returned on every searchResultsDone message, not just 
the last one of the paged results request. Of course, the sortKeyResponseControl 
might not be returned if there is an error processing the paged results request or 
there are no search results to return. Additionally, when sorted search is requested 
along with simple paged results, the Server sends the search results so rted base d 
on the entire search result set and does not simply sort each page. See 
paged results of search results" on page 98 for more information. 


'Simple 


When chasing referrals, the dient application must send in a sorted search request 
to each of the referral Servers. It is up to the application using the client's Services 
to decide whether or not to set the criticality as to the support of sorted search 
results, and to handle a lack of support of this control on referral Servers as 
appropriate based on the application. Additionally, the LDAP Server does not 
ensure that the referral Server supports the sorted search control. Multiple lists 
might be returned to the dient application, some of which are not sorted. It is the 
dient application's decision as to how best to present this information to the end 
user. Possible Solutions include: 

• Combine all referral results before presenting to the end user 

• Show multiple lists and the corresponding referral Server host name 

• Take no extra steps and show all results to the end user as they are returned 
from the Server 

The dient application must turn off referrals to get one truly sorted list; otherwise, 
when chasing referrals with the sorted search control specified, unpredictable 
results can occur. 


More information about the Server side sorted search control, with control OID of 
1.2.840.113556.1.4.473, can be found in RFC 2891 - LDAP Control Extension for 
Server Side Sorting of Search Results. 


Errors 


The sort r outines return an LDAP error code if they encounter an error parsing the 
result. See "LDAP_ERROR" on page 61 for a list of the LDAP error codes. 


Notes 

SortString, sortKeyList, Controls, serverControls, and attribute must be freed by the 
caller. 


See also 


ldap_search| |ldap_parse_result 
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Chapter 4. Using gsk7IKM 


The following key-management program is provided with the Global Security Kit 
(GSKit): 

• gsk7IKM - A user-friendly GUI for managing key database files, implemented as 
a Java applet. 

Note: On the AIX operating Systems, if you are prompted to set JAVA_HOME, you 
can set it to either the system-installed Java or the Java Version included 
with the IBM Directory Server. If you use the IBM Directory Server version, 
you also need to set the LIBPATH environment variable as follows: 
export LIBPATH=/usr/1dap/java/bin:/usr/ldap/java/bin/classic:$LIBPATH 

Use this utility to create public-private key pairs and certificate requests, receive 

certificate requests into a key database file, and manage keys in a key database file. 

The tasks you can perform with gsk7IKM include: 

• Creating a key pair and requesting a certificate from a certificate authority 

• Receiving a certificate into a key database file 

• Managing keys and certificates 

- Changing a key database password 


Showing information about a key 


Deleting a key 



Making a key the default key in the key database 


Creating a key pair and certificate request for self-signing 

Exporting a key 



Importing a key into a key database 


- Designating a key as a trusted root 

- Removing trusted root key designation 

- Requesting a certificate for an existing key 
Migrating a keyring file to the key database format 


Creating a key pair and requesting a certificate from a Certificate 
Authority 

If your dient application is connecting to an LDAP Server that requires dient and 
Server authentication, then you need to create a public-private key pair and a 
certificate. 


If your dient application is connecting to an LDAP Server that only requires Server 
authentication, it is not necessary to create a public-private key pair and a 
certificate. It is sufficient to have a certificate in your dient key database file that is 
marked as a trusted root. If the Certification Authority (CA) that issued the 
server's certificate is not already defined in your dient key database, you need to 
request the CA's certif icate from the CA, receive it into your key databas e, and 


mark it as trusted. See 


'Designating a key as a trusted root" on page 155 
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Your dient uses its private key to sign messages sent to Servers. The Server sends 
its public key to clients so that they can encrypt messages to the Server, which the 
Server decrypts with its private key. 

To send its public key to a Server, the dient needs a certificate. The certificate 
contains the client's public key, the Distinguished Name associated with the client's 
certificate, the serial number of the certificate, and the expiration date of the 
certificate. A certificate is issued by a CA, which verifies the identity of the dient. 


The basic steps to create a certificate that is signed by a CA are: 

1. Create a certificate request using gsk7IKM. 

2. Submit the certificate request to the CA. This can be done using e-mail or an 
on-line Submission from the CA's Web page. 

3. Receive the response from the CA to an accessible location on the file System of 
your Server. 


4. 


Receive the certificate into your key database file 


Note: If you are obtaining a signed dient certificate from a CA that is not in the 

default list of trusted CAs, you need to obtain the CA's certificate, receive it 
into your key database and mark it as trusted. This must be done betöre 
receiving your signed dient certificate into the key database file. 


To create a public-private key pair and request a certificate: 

1. Start gsk7IKM Java utility by typing: 
gsk7IKM 

2. Select Key Database File. 

3. Select New (or Open if the key database already exists). 

4. Specify key database file name and location. Type OK. 

Note: A key database is a file that the dient or Server uses to störe one or 
more key pairs and certificates. 

5. When prompted, supply password for the key database file. Click OK. 

6. Select Create. 

7. Select New Certificate Request. 

8. Supply user-assigned label for key pair. The label identifies the key pair and 
certificate in the key database file. 

9. If you are requesting a low-assurance dient certificate, enter the common 
name. This must be unique and the full name of the user. 

10. If you are requesting a high-assurance secure Server certificate, then: 

• Enter the X.500 common name of the Server. Usually this is the TCP/IP 
fully qualified host name, for example, www.ibm.com. For a VeriSign Server 
certificate, it must be the fully qualified host name. 

• Enter the Organization name. This is the name of your Organization. For a 
VeriSign secure Server certificate, if you already have an account with 
VeriSign, the name in this field must match the name on that account. 

• Enter the organizational unit name. This is an optional field. 

• Enter the locality/city where the Server is located. This is an optional field. 

• Enter a three-character abbreviation of the state/province where the Server 
is located. 

• Enter the postal code appropriate for the server's location. 

• Enter the two-character country code where the Server is located. 
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11. Click OK. 

12. A message identifying the name and location of the certificate request file is 
displayed. Click OK. 


13. Send the certificate request to the CA. 

If this is a request for a VeriSign low assurance certificate or secure Server 
certificate, you must e-mail the certificate request to VeriSign. 


You can mail the low assurance certificate request to VeriSign immediately. A 
secure Server certificate request requires more documentation. To find out 
what VeriSign r equires for a secure Server certif icate request, go to the 


following URL: http://www.verisign.com/ibm 


14. When you receive the certificate from the CA, use g sk7IKM to receive it into 


the key database whe re you stored the key pair. See "Receiving a certificate 


into a key database' 


Note: Change the key database password frequently. If you specify an expiration 
date, you need to keep track of when you need to change the password. If 
the password expires before you change it, the key database is not usable 
until the password is changed. 


Receiving a certificate into a key database 

After receiving a response from your CA, you need to receive the certificate into a 
key database. 

To receive a certificate into a key database: 

1. Type gs k71 KM to start the Java utility. 

2. Select Key Database File. 

3. Select Open. 

4. Specify key database file name and location. Type OK. 

5. When prompted, supply password for the key database file, click OK. 

6. Select Create. 

7. Select Personal Certificates in the middle display window. 

8. Click Receive. 

9. Enter name and location of the certificate file that contains the signed 
certificate, as received from the CA. Click OK. 


Changing a key database password 

To change a key database password: 

1. Type gsk71 KM to start the Java utility. 

2. Select Key Database File. 

3. Select Open. 

4. Specify key database file name and location. Type OK. 

5. When prompted, supply password for the key database file. Click OK. 

6. Select Key Database File. 

7. Select Change Password. 

8. Enter <New Password>. 

9. Confirm <New Password>. 

10. Select and set optional password expiration time. 
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11. Select Stash the password to a file? if you want the password to be encrypted 
and stored on disk. 

12. Click OK. 

13. A message is displayed with the file name and location of the stash password 
file. Click OK. 

Note: The password is important because it protects the private key. The private 
key is the only key that can sign documents or decrypt messages encrypted 
with the public key. 

Showing Information about a key 

To show information about a key, such as its name, size or whether it is a trusted 
root: 

1. Type gs k71 KM to start the Java utility. 

2. Select Key Database File. 

3. Select Open. 

4. Specify key database file name and location. Type OK. 

5. When prompted, supply password for the key database file. Click OK. 

6. To see information about keys designated as Personal Certificates: 

• Select Personal Certificates at the top of the Key database content window. 

• Select a certificate. 

• Click View/Edit to display information about the selected key. 

• Click OK to return to the list of Personal Certificates. 

7. To see information about keys that are designated as Signer Certificates: 

• Select Signer Certificates at the top of the Key database content window. 

• Select a certificate . 

• Click View/Edit to display information about the selected key. 

• Click OK to return to the list of Signer Certificates. 

Deleting a key 

To delete a key: 

1. Type gsk71 KM to start the Java utility. 

2. Select Key Database File. 

3. Select Open. 

4. Specify key database file name and location. Type OK. 

5. When prompted, supply password for the key database file. Click OK. 

6. Select the type of key you want to delete at the top of the Key database 
content window (Personal Certificates, Signer Certificates, or Personal 
Certificate Requests). 

7. Select a certificate. 

8. Click Delete. 

9. Click Yes to confirm. 
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Making a key the default key in the key database 

The default key must be the private key the Server uses for its secure 
Communications. 

To make a key the default key in the key database: 

1. Type gs k71 KM to start the Java utility. 

2. Select Key Database File. 

3. Select Open. 

4. Specify key database file name and location. Type OK. 

5. When prompted, supply password for the key database file. Click OK. 

6. Select Personal Certificates at the top of the Key database content window. 

7. Select the desired certificate. 

8. Click View/Edit. 

9. Select the Set the certificates as the default box. Click OK. 


Creating a key pair and certificate request for self-signing 

By definition, a secure Server must have a public-private key pair and a certificate. 

The Server uses its private key to sign messages to clients. The Server sends its 
public key to clients so they can encrypt messages to the Server, which the Server 
decrypts with its private key. 

The Server needs a certificate to send its public key to clients. The certificate 
contains the server's public key, the Distinguished Name associated with the 
server's certificate, the serial number of the certificate, and the expiration date of 
the certificate. A certificate is issued by a CA, who verifies the identity of the 
Server. 

You can request one of the following certificates: 

• A low assurance certificate from VeriSign, best for non-commercial purposes, 
such as a beta fest of your secure environment 

• A Server certificate to do commercial business on the Internet from VeriSign or 
some other CA 

• A self-signed Server certificate if you plan to act as your own CA for a private 
Web network 


For information about using a CA such as VeriSign to sign the Server certificate. 


see 

"Creatin 

y a key pair and requesting a certificate from a Certificate Authority" 

on page149 



The basic steps to creating a self-signed certificate are: 

1. Type gsk71 KM to start the Java utility. 

2. Select Key Database File. 

3. Select New, or Open if the key database already exists. 

4. Specify key database file name and location. Type OK. 

Note: A key database is a file that the dient or Server uses to störe one or more 
key pairs and certificates. 

5. When prompted, supply password for the key database file. Click OK. 

6. Click New Self-signed. 
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7. Supply the following: 

• User-assigned label for key pair. The label identifies the key pair and 
certificate in the key database file. 

• Select the desired certificate Version. 

• Select the desired Key Size. 

• Enter the X.500 common name of the Server. Usually this is the TCP/IP fully 
qualified host name, for example, www.ibm.com. 

• Enter the Organization name. This is the name of your Organization. 

• Enter the organizational unit name. This is an optional field. 

• Enter the locality/city where the Server is located. This is an optional field. 

• Enter a three-character abbreviation of the state/province where the Server is 
located. 

• Enter the zipcode appropriate for the server's location. 

• Enter the two-character country code where the Server is located. 

• Enter the Validity Period for the certificate. 

8. Click OK. 


Exporting a key 


If you need to transfer a key pair or certificate to another Computer, you ca n export 
the key pair from its key database to a file. On the other Computer, you can 
the key pair into a key ring. 


iport 


To export a key from a key database: 

1. Type gs k71 KM to start the Java utility. 

2. Select Key Database File. 

3. Select Open. 

4. Specify key database file name and location. Type OK. 

5. When prompted, supply password for the key database file. Click OK. 

6. Select Personal Certificates at the top of the Key database content window. 

7. Select the desired certificate. 

8. Click Export/Import. 

9. For Action Type, select Export Key. 

10. Select the Key file type: 

• PKCS12 file 

• CMS Key database file 

• Keyring file (as used by mkkf) 

• SSLight key database dass 

11. Specify a file name. 

12. Specify location. 

13. Click OK. 

14. Enter the required password for the file. Click OK. 
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Importing a key 

To import a key into a key ring: 

1. Type gsk71 KM to start the Java utility. 

2. Select Key Database File. 

3. Select Open. 

4. Specify key database file name and location. Type OK. 

5. When prompted, supply password for the key database file. Click OK. 

6. Select Personal Certificates at the top of the Key database content window. 

7. Select the desired certificate. 

8. Click Export/Import. 

9. For Action Type, select Import Key. 

10. Select the desired Key file type. 

11. Enter the file name and location. 

12. Click OK. 

13. Enter the required password for the source file. Click OK. 

Designating a key as a trusted root 

A trusted root key is the public key and associated Distinguished Name of a CA. 
The following trusted roots are automatically defined in each new key database: 

• Integrion Certification Authority Root 

• IBM World Registry Certification Authority 

• Thawte Personal Premium CA 

• Thawte Personal Freeemail CA 

• Thawte Personal Basic CA 

• Thawte Premium Server CA 

• VeriSign Test CA Root Certificate 

• RSA Secure Server Certification Authority 

• VeriSign dass 1 Public Primary Certification Authority 

• VeriSign dass 2 Public Primary Certification Authority 

• VeriSign dass 3 Public Primary Certification Authority 

• VeriSign dass 4 Public Primary Certification Authority 

Note: Each of these trusted roots are initially set to be trusted roots by default. 

To designate a key as a trusted root: 

1. Type gs k71 KM to start the Java utility. 

2. Select Key Database File. 

3. Select Open. 

4. Specify key database file name and location. Type OK. 

5. When prompted, supply password for the key database file. Click OK. 

6. Select Signer Certificates at the top of the Key database content window. 

7. Select the desired certificate. 

8. Click View/Edit. 

9. Check the Set the certificate as a trusted root box, and click OK. 

10. Select Key Database File and then select Close. 
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Removing a key as a trusted root 

A trusted root key is the public key and associated Distinguished Name of a CA. 
The following trusted roots are automatically defined in each new key database: 

• Integrion Certification Authority Root 

• IBM World Registry Certification Authority 

• Thawte Personal Premium CA 

• Thawte Personal Freeemail CA 

• Thawte Personal Basic CA 

• Thawte Premium Server CA 

• VeriSign Test CA Root Certificate 

• RSA Secure Server Certification Authority 

• VeriSign dass 1 Public Primary Certification Authority 

• VeriSign dass 2 Public Primary Certification Authority 

• VeriSign dass 3 Public Primary Certification Authority 

• VeriSign dass 4 Public Primary Certification Authority 

Note: Each of these trusted roots are initially set to be trusted roots by default. 

To remove the trusted root Status of a key: 

1. Type gs k71 KM to start the Java utility. 

2. Select Key Database File. 

3. Select Open. 

4. Specify key database file name and location. Type OK. 

5. When prompted, supply password for the key database file. Click OK. 

6. Select Signer Certificates at the top of the Key database content window. 

7. Select the desired certificate. 

8. Click View/Edit. 

9. Clear the Set the certificate as a trusted root check box. Click OK. 

10. Select Key Database File and then select Close. 

Requesting a certificate for an existing key 

To create a certificate request for an existing key: 

1. Type gsk71 KM to start the Java utility. 

2. Select Key Database File. 

3. Select Open. 

4. Specify key database file name and location. Type OK. 

5. When prompted, supply password for the key database file. Click OK. 

6. Select Personal Certificates at the top of the Key database content window. 

7. Select the desired certificate. 

8. Click Export/Import. 

9. For Action Type, select Export Key. 

10. Select the desired Data Type: 

• Base-64-encoded ASCII data 

• Binary DER data 

• SSLight Key Database Class 
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11. Enter the certificate file name and location. 

12. Click OK. 

13. Select Key Database File and then select Close. 

Send the certificate request to the CA. 

If this is a request for a VeriSign low assurance certificate or secure Server 
certificate, you must e-mail the certificate request to VeriSign. 

You can mail the low assurance certificate request to VeriSign immediately. A 
secure Server certificate request requires more documentation. To find out what 
VeriSign requires for a secure Se rver certificate request, go to the following URL: 
http://www.verisign.com/ibm 


Migrating a keyring file to the key database format 

The gsk7IKM program can be used to migrate an existing keyring file, as created 
with mkkf, to the format used by gsk7IKM. 

To migrate a keyring file: 

1. Type gsk71 KM to start the Java utility. 

2. Select Key Database File. 

3. Select Open. 

4. Specify key database file name and location. Type OK. 

5. When prompted, supply password for the keyring file. Click OK. 

6. Select Key Database File. 

7. Select Save As.... 

8. Select CMS key database file as the Key database type. 

9. Specify a file name. 

10. Specify location. 

11. Click OK. 
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Chapter 5. Event notification 

The event notification function allows a Server to notify a registered dient that an 
entry in the directory tree has been changed, added or deleted. This notification is 
in the form of an unsolicited message. 


Registration request 

In order to register, the dient must use a bound connection. To register a dient use 
the supported dient APIs for extended operations. An LDAP v3 extended 
Operation request has the form: 

ExtendedRequest [APPLICATION 23] SEQUENCE { 
requestName [0] LDAPOID, 
requestValue [1] OCTET STRING OPTIONAL } 

where the requestValue has the form: 

requestValue = SEQUENCE { 

eventID ENUMERATED { 

LDAP_CHANGE (0)}, 
baseObject LDAPDN, 

scope ENUMERATED { 


baseObject 

(0), 

singleLevel 

(1), 

wholeSubtree 

(2) } 

type INTEGER OPTIONAL } 


and where type has the form: 


changeType ::= ENUMERATED { 


changeAdd 

(1), 

changeDelete 

(2), 

changeModify 

(4), 

changeModDN 

(8) } 


Note: If the type field is not specified, it defaults to all changes. 

An LDAP v3 extended Operation response has the form: 

ExtendedResponse ::= [APPLICATION 24] SEQUENCE { 
C0MP0NENTS OF LDAPResult, 
responseName [10] LDAPOID OPTIONAL, 

response [11] OCTET STRING OPTIONAL } 


Registration response 

If the registration is successful, the Server retums the following message and a 
unique registration ID: 

LDAP_SUCCESS <registration ID> 

If the registration fails, the Server returns one of the following: 
LDAP_UNWILLING_TO_PERFORM 

This error code is returned if: 

• The event notification function is tumed off in the Server. 

• The event ID requested by the dient cannot be handled by the Server. 
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• The dient is unbound. 

LDAP_N0_SUCH_0BJ ECT 

This error code is returned if: 

• The base DN supplied by the dient does not exist or is not visible to the dient. 
LDAP_N0T_SUPP0RTED 

This error code is returned if: 

• The change type supplied by the dient cannot be handled by the Server. 

Usage 

When an event occurs, the Server sends a message to the dient as an LDAP v3 
unsolicited notification. The message ID is 0 and the message is in the form of an 
extended Operation response. The responseName field is set to the registration 

OID. The response field contains the unique registration ID and a timestamp for 
when the event occurred. The time field is in Coordinated Universal Time (UTC) 
format. 

Note: When a transaction occurs, the event notifications for the transaction steps 
cannot be sent until the entire transaction is completed. 


Unregistering a dient 

Set the requestName field to the unregister request OID. In the requestValue field 



type the unique registration ID returned by the Server from the registration 
request: 

requestValue ::= OCTET STRING 

If the registration is successfully removed, the LDAPResult field contains 
LDAP_SUCCESS and the response field contains the registration ID that was 
removed. 

If the unregistration request was unsuccessful, NO_SUCH_OBJECT is returned. 

Example 

linclude <stdio.h> 
linclude <string.h> 
linclude <ldap.h> 


struct berval *create_reg(int id.char *base,int scope.int type){ 
struct berval *ret; 

BerElement *ber; 

if((ber = ber_al1oc_t(1)) == NULL){ 
printf("ber_al1oc_t fai1ed\n"); 
return NULL; 

} 

if(ber_printf(ber,"{esi",id,base,scope) == (-1)){ 
printf("first ber_printf failed\n"); 
return NULL; 

} 

if (type != (-1)) { 

i f(ber_printf(ber,"i", type) == (-1)){ 
printf("type ber_printf failed\n"); 
return NULL; 
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} 

} 

if(ber_printf(ber,"}") == (-1)){ 
printf("closing ber_printf failed\n"); 
return NULL; 

} 


if(ber_flatten(ber,&ret) == (-1)){ 
printf("ber_flatten fai1ed\n"); 
return NULL; 

} 

ber_free(ber,1); 
return ret; 

} 

int main(int argc,char **argv){ 

LDAP *ld; 

char *oidreq = "1.3.18.0.2.12.1"; 
char *oidres; 

struct berval *valres = NULL; 
struct berval *registration; 
int rc,version, port; 

LDAPMessage *res; 

BerElement *ber; 
char *regID; 

arge--; argv++; 

port = 389; 
if(arge > 0){ 

if(argc > 1) sscanf(argv[l],"%d"port); 

Id = ldap_init(argv[0] ,port); 

} 

el se 

Id = ldap_init("localhost",389); 
i f (1 d == NULL) { 
printf("ldap_init fai1ed\n"); 

1 dap_unbi nd(1 d); 
return -1; 

} 

version = 3; 

1dap_set_option(1d,LDAP_0PT_PR0T0C0L_VERSI0N,&version); 

if(1dap_simple_bind_s(1d,"cn=admin","secret") != LDAP_SUCCESS){ 
printf("Couldn 1 t bind\n"); 

1 dap_unbi nd (Id); 
return -1; 

} 


registration = create_reg(0,"o=ibm,c=us",2,15); 

rc = ldap_extended_operation_s(ld,oidreq,registration,NULL,NULL, 

&oidres,&valres); 

if(rc == LDAP_SUCCESS){ 
if(valres != NULL){ 
if((ber = ber_init2(valres)) == NULL) 
printf("ber_init2 failed\n"); 
el se{ 

if(ber_scanf(ber,"a",&regID) == LBER_ERROR) 
printf("ber_scanf failed\n"); 
printf("registration ID: %s\n",regID); 
ber_free(ber,1); 

} 


el se{ 

printf("valres NULL\n"); 

} 

} 
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el se{ 

printf("extended Operation failed Ox%x\n",rc); 

} 


// Wait for notifications 

printf("result: %d\n",1dap_result(1d,0,LDAP_MSG_ONE,NULL,&res)) 

1dap_memfree(regID); 
ldap_unbind(ld); 
return 0; 

} 
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Chapter 6. LDAP dient plug-in programming reference 


The following sections provide information about writing dient plug-ins. 


Introduction to dient SASL plug-ins 

Client-side SASL plug-ins are used to extend the authentication capabilities of the 
LDAP dient library. They work by intercepting the application's invocation of the 
ldap_sasl_bind_s() API. Note that SASL plug-ins are not designed to intercept 
asynchronous SASL binds. 

Basic Processing 

The following describes the typical flow when a SASL plug-in is used to provide 
an extended authentication function. This flow assumes the SASL plug-in shared 
library has already been loaded by the LDAP library: 

1. Application invokes ldap_sasl_bind_s(), with a mechanism supported by a 
configured SASL plug-in. 

2. The LDAP library invokes the SASL bind worker function, as provided by the 
appropriate plug-in. The parameters supplied on the original ldap_sasl_bind_s() 
API are passed to the plug-in as elements of a pblock structure. 

3. The plug-in's worker function receives control, and extracts the parameters 
from the pblock using the ldap_plugin_pblock_get() API. The following 
SASL-related information can be obtained from the pblock by the plug-in: 

• Distinguished Name (dn) 

• Credentials 

• Server Controls 

• Client Controls 

• Mechanism (plug-in subtype) 

In addition to these parameters, the plug-in can also obtain other information 
using the ldap_plugin_pblock_get(), including: 

• Plug-in configuration information (that is, configuration information supplied 
in ARGC and ARGV form) 

• Target LDAP Server host name 

4. The plug-in performs its mechanism-specific logic. Here are some sample 
mechanisms that can be implemented as SASL plug-ins, and thus be made 
available to all LDAP applications running on the System: 

Authentication based on a user's fingerprint (for example, 
mechanism=userfp) 

When the fingerprint plug-in gets control, it uses the DN supplied on 
the ldap_sasl_brnd_s() API to obtain an image of the user's fingerprint. 
This can entail prompting the user to use a fingerprint scanning device. 
In this example, the fingerprint image, however obtained, represents 
the user's credentials. 

Once the credentials are obtained, the plug-in is ready to perform the 
actual SASL bind. This is done by invoking the 

ldap_plugin_sasl_bind_s() API, supplying the appropriate parameters 
(DN, credentials, mechanism, Server Controls). This is a synchronous 
API that sends the SASL bind request to the LDAP Server. Two items 
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are returned to the plug-in when the bind result is returned from the 
Server, and control is returned to the plug-in: 

• Bind result error code 

• Server credentials 

If the Server credentials are to be returned to the application, they must 
be set in the pblock prior to returning control to the LDAP library, and 
subsequently to the application. This is done by using 
ldap_plugin_pblock_set(). In this example, the plug-in's work is 
complete, and it returns, supplying the bind result error code as the 
return code. 

Authentication using credentials previously established by the operating 
System 

When the plug-in gets control, it queries the local security context to 
obtain the user's identity and security token. For this example, we 
assume the user's identity, as associated with the local security context, 
is used to construct the DN, and information from the security token is 
used for credentials. 

After the credentials are obtained, the plug-in invokes 
ldap_plugin_sasl_bind_s(), supplying the appropriate parameters (DN, 
credentials, mechanism, Server Controls). As in the previous example, 
the plug-in waits for the results of the bind request, then returns to the 
LDAP library, again setting Server credentials in the pblock, if 
appropriate. Control is then returned to the application, along with the 
optional Server credentials. 

Authentication using multiple binds (mechanism=cram-md5) 

Some SASL mechanisms require multiple transactions between the 
dient and the Server (for example, the SASL cram-md5 mechanism). 

For this type of mechanism, once the plug-in gains control, it actually 
invokes the ldap_plugin_sasl_bind_s() API multiple times. On each 
bind Operation, the plug-in can supply DN, credentials, mechanism and 
Server Controls, which are passed to the Server. The LDAP Server can 
return a result and Server credentials back to the dient. The plug-in can 
use this information to formulate another bind, again sent to the Server 
using ldap_plugin_sasl_bind_s(). Once the multi-bind flow is complete, 
the plug-in returns control to the LDAP library with the result and 
optional Server credentials. 


Restrictions 

The plug-in must not use any LDAP APIs which accept ld as the input. This 
results in deadlock, since the ld is locked until the bind processing is complete. 


Initializing a plug-in 

A typical LDAP SASL plug-in contains two entry points: 

• An initialization routine 

• A worker routine, which implements the authentication function 

When an instance of an application uses a SASL plug-in for the first time, the 
LDAP library obtains the configuration information for the plug-in. The 
configuration information can come from ibmldap.conf or might have been 
supplied explicitly by the application with the ldap_register_plugin() API. 
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Once the configuration information is located, the LDAP library loads the plug-in's 
shared library and invoke its initialization routine. By default, the name of the 
initialization routine for a plug-in is ldap_plugin_init(). A different entry point can 
be defined in ibmldap.conf, or supplied on the ldap_plugin_register() API if the 
plug-in is explicitly registered by the application. 

The plug-in's initialization routine is responsible for supplying the address of its 
worker routine's entry point, which actually implements the authentication 
function. This is done by using ldap_plugin_pblock_set() to define the address of 
the worker routine's entry point in the pblock. For example, the following code 
segment depicts a typical initialization routine, where 

authenticate_with_fingerprint is the name of the routine provided by the plug-in to 
perform a fingerprint-based authentication: 

int 1dap_plugin_init ( LDAP_Pblock *pb ) 

{ 

int rc; 

rc = 1dap_plugin_pblock_set ( pb, LDAP_PLUGIN_SASL_BIND_S_FN, ( void * ) 

authenticate_with_fingerprint ); 

if ( rc != LDAP_SUCCESS ) printf("ldap_plugin_init couldn't initialize 
worker function\n"); 
return ( rc ); 

} 

A pblock is an opaque structure in which parameters are stored. A pblock is used 
to communicate between the LDAP dient library and a plug-in. The 
ldap_plugin_pblock_set and ldap_plugin_pblock_get APIs are provided for your 
plug-in to set, or get, parameters in the pblock structure. 

Using ldap_plugin_pblock_get(), the plug-in can also access configuration 
parameters. For example, the following code segment depicts how the plug-in can 
access its configuration information: 

int arge; 
char ** argv; 

rc = 1dap_plugin_pblock_get ( pb, LDAP_PLUGIN_ARGC, &argc ); 
if (rc != LDAP_SUCCESS) 
return (rc); 

rc = ldap_plugin_pblock_get( pb, LDAP_PLUGIN_ARGV, &argv ); 
if (rc != LDAP_SUCCESS) 
return (rc); 


If the plug-in's initialization processing is significant, and the results need to be 
preserved and made available to the plug-in's worker function, the initialization 
routine can störe the results of initialization as private instance data in its shared 
library. When the plug-in's worker function is subsequently invoked, it can access 
this private instance data. For example, during initialization, the plug-in might 
need to establish a session with a remote security Server. Session information can 
be retained in the private instance data, which can be accessed later by the 
plug-in's worker function. 


After your plug-in is correctly initialized, its worker function can be used by the 
LDAP library. Continuing the example shown above, if the mechanism supported 
by the plug-in is userfp, the authenticate_with_fingerprint function of your plug-in 
is invoked when the appl ication issues an ldap sasl bind s() fun ction with 


mechanism="userfp". See "Sample worker function" on page 168 for an example of 
a plug-in's worker function. 
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Writing your own SASL plug-in 

Do the following to write your own SASL plug-in: 

1. Implement your own initialization and worker functions. Include ldap.h, where 
you can find all the parameters that can be obtained from the pblock, as well as 
the function prototypes for the available plug-in functions: 

• ldap_plugin_pblock_get() 

• ldap_plugin_pblock_set() 

• ldap_plugin_sasl_bind_s() 

2. Identity the input parameters to your initialization and worker functions. 

Note: The LDAP library can pass parameters to your plug-in initialization 

function by way of the argument list that is specified in ibmldap.conf, or 
by way of the plugin_parmlist parameter on the ldap_register_plugin() 
API. Information might also be supplied as client-side Controls. 

3. The initialization function must call the ldap_plugin_pblock_set API in order to 
register your plug-in's worker function. 

4. Implement your worker function. The worker function is responsible for 
obtaining the user's credentials and implementing the authentication function. 
Typically this involves invoking the ldap_plugin_sasl_bind_s() API one or more 
times. If the authentication is successful, LDAP_SUCCESS must be returned. 
Otherwise, the unsuccessful LDAP result must be returned as the return code. 

If appropriate, the worker function can also return a value for Server 
credentials. 

5. Export your initialization function from your plug-in library. Use an .exp file 
for the AIX operating System or Solaris operafing System, or a .def (or 
dllexport) file for the Windows NT operating System to export your 
initialization function. 

6. Compile your dient plug-in functions. Set the include path to include ldap.h, 
and to link to ldap.lib. Compile and link all your LDAP plug-in object files 
with whatever libraries you need, including ldap.lib. Make sure that the 
initialization function is exported from the .dll you created. 

7. Add a plug-in directive in the LDAP plug-in configuration file, ibmldap.conf. 
Altematively, the application can define the plug-in by calling the 
ldap_register_plugin() API. 


Plug-in APIs 


For pblock access: 

int ldap_plugin_pblock_get( LDAP_PB1ock *pb, 
int ldap_plugin_pblock_set( LDAP_PB1ock *pb, 

For sending an LDAP bind to the Server: 

int ldap_plugin_sasl_bind_s ( 


i nt 
i nt 


arg, 

arg. 


voi d 
voi d 


**value 
*value ) 


LDAP 
char 
char 

struct berval 
LDAPControl 
LDAPControl 
struct berval 


*ld, 

*dn, 

*mechanism, 
*credentials, 
**serverctrls, 
**clientctrls, 
**servercredp) 


166 


C-Client SDK Programming Reference 




ldap_plugin_pblock_get() 

The ldap_plugin_pblock_get() API returns the value associated with the specified 
pblock tag. 

Syntax 

finclude "ldap.h" 

int ldap_plugin_pblock_get( LDAP_PBlock *pb, int arg, void **value ) 

Parameters 

pb Specifies the address of a pblock. 

arg Specifies the tag or ID of the tag-value pair that you want to obtain from 
the pblock. 

value Specifies a pointer to the address of the returned value. 

Returns 

Returns 0 if successful, or -1 if an error occurs. 

ldap_plugin_pblock_set() 

The ldap_plugin_pblock_set API sets the value associated with the specified pblock 
tag. 

Syntax 

#include "ldap.h" 

int ldap_plugin_pblock_set( LDAP_PBlock *pb, int arg, void *value ); 

Parameters 

pb Specifies the address of a pblock. 

arg Specifies the tag or ID of the tag-value pair that you want to set in the 
pblock. 

value Specifies a pointer to the value that you want to set in the parameter block. 

Returns 

Returns 0 if successful, or -1 if an error occurs. 


Idap_plugin_sasl_bind_s() 

The ldap_plugin_sasl_bind_s API is used by the plug-in to transmit an LDAP 
SASL bind Operation to the LDAP Server. 


Syntax 

#include "ldap.h" 

int 1dap_plugin_sasl_bind_s( 

LDAP 

char 

char 

struct berval 
LDAPControl 
LDAPControl 
struct berval 


*1 d, 

*dn, 

*mechanism, 
*credentials, 
**serverctrl s, 
**clientctrls, 
**servercredp) 


Parameters 


ld 


Specifies the LDAP pointer associated with the application's invocation of 


ldap_sasl_bind_s() The plug-in obtains the LD with the 


ldap_plugin_pblock_get() API. 


dn Specifies the |Distinguished Name| to bind the entry. The DN might have 
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been supplied by the application and obtained using 
ldap_plugin_pblock_get(), or it might have been obtained by other means. 

credentials 

Specifies the credentials to authenticate with. Arbitrary credentials can be 
passed using this parameter. The credentials might have been supplied by 
the application and obtained using ldap_plugin_pblock_get(), or they 
might have been obtained by other means. 


mechanism 

Specifies the SASL mechanism to be used when binding to the Server. If a 
plug-in can be invoked for more than one mechanism, the plug-in can 
obtain the mechanism that was specified by the application with the 
ldap_plugin_pblock_get() API. 


serverctrls 

Specifies a list of LDAP Server Controls. See 
for more information about Server Controls. 


'LDAP Controls" on page 58 


The Server Controls might have 
been supplied by the application and obtained using 
ldap_plugin_pblock_get(), or they might have been obtained by other 


means. 


clientctrls 


Specifies a list of LDAP dient Controls. See pLDAP Controls" on page 58 for 
more information about dient Controls. 


Note: The dient Controls are not supported at this time for the 
ldap_plugin_sasl_bind_s() API. 


Returns 

error code 

The error code is set to LDAP_SUCCESS if the bind succeeded. Otherwise it is 
set to a nonzero error code. 

servercredp 

This result parameter is set to the credentials returned by the Server. If no 
credentials are returned, it is set to NULL. 


Sample worker function 

/* Sample SASL Plugin */ 

linclude <1dap.h> 


int 1dap_plugin_sasl_bind_s 

{ 

LDAP 

char 

char 

struct berval 
LDAPControl 
LDAPControl 
struct berval 

void * 
i nt 


prepare ( LDAP_Pblock *pb ) 

*1 d; 

*dn; 

*mechanism; 

*cred; 

**serverctrls; 

**clientctrls; 
*servercredp = NULL; 

data; 

rc; 


^-k^k-k-k^k-k-k'k-k-k'k-k-k'krk^k-k'k^k-k-k'k-k-k'k-k-k-k-k-k-k'k^k-k'k^k-k-k'k-k-k'k-k-k-k'k-k-k'k^k-k-k^k-k-k'k-k-k'k-k-k-k'k^k-k'k^k-k-k'k-k-k'k-k/ 

/* Query pblock to obtain ld, dn, mechanism, credentials, Server Controls */ 
/* and dient Controls, as supplied by application when it invoked the */ 
/* 1dap_sasl_bind_s () API. */ 
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/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 


if ( rc = ( 1dap_plugin_pblock_get ( pb, LDAP_PLUGIN_LD, &data ))){ 
printf( "Could not get parameter for bind operation\n" ); 
return ( rc ); 


ld = ( LDAP * ) data; 
if ( rc = ( 1dap_plugin_pblock_get ( pb, 
&data ))) 

return ( rc ); 
dn = ( char * ) data; 
if ( rc = ( 1dap_plugin_pblock_get ( pb, 
&data ))) 

return ( rc ); 

mechanism = ( char * ) data; 
if ( rc = ( 1dap_plugin_pblock_get ( pb, 
&data ))) 

return ( rc ); 

cred = ( struct berval * ) data; 
if ( rc = ( 1dap_plugin_pblock_get ( pb, 
&data ))) 

return ( rc ); 

serverctrls = ( LDAPControl ** ) data; 
if ( rc = ( 1dap_plugin_pblock_get ( pb, 
&data ))) 

return ( rc ); 

clientctrls = ( LDAPControl ** ) data; 


LDAP_P LUG IN_SAS L_DN, 


LDAP_PLUGIN_SASL_BIND_MECHANISM, 


LDAP_PLUGIN_SASL_BIND_CREDENTIALS, 


LDAP_PLUGIN_SASL_BIND_SERVERCTRLS, 


LDAP_PLUGIN_SASL_BIND_CLIENTCTRLS, 


/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

/* Perform plugin specific logic here to alter or obtain the user's */ 

/* distinguished name, credentials, etc. This could include obtaining */ 


/* 

additional data from 

the pblock, including: 

*/ 

/* 



*/ 

/* 

LDAP PLUGIN TYPE 

(e.g. "sasl") 

*/ 

/* 

LDAP PLUGIN ARGV 

plugin config variables 

*/ 

/* 

LDAP PLUGIN ARGC 

plugin config variable count 

*/ 

/* 



*/ 


/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 


if ( rc = ( ldap_plugin_sasl_bind_s ( 

ld, 

dn, 

mechanism, 
cred, 

serverctrls, 

clientctrls, 

&servercredp))) 

return rc; 

data = ( void * ) servercredp; 

if ( rc = ( 1dap_plugin_pblock_set ( pb, LDAP_PLUGIN_SASL_SERVER_CREDS, 
&data ))) 

return rc; 


} 


return ( LDAP_SUCCESS ); 


1dap_plugin_init ( LDAP_Pblock *pb ) 

{ 

int arge; 

char **argv; 

if ( rc = (ldap_plugin_pblock_set ( pb, LDAP_PLUGIN_SASL_BIND_S_FN, 

(void * ) 
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1dap_plugin_sasl_bind_s_prepare ))) 
return ( rc ); 

return ( LDAP_SUCCESS ); 

} 
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Appendix A. Possible extended error codes returned by LDAP 
SSL function codes 


The following are values returned by all function calls: 

• 0 -The task completed successfully. Issued by every function call that completes 
successfully. 

• 1 - The environment or SSL handle is not valid. The specified handle was not 
the result of a successful open function call. 

• 2 - The dynamic link library unloaded (Windows only). 

• 3 - An internal error occurred. Report this error to service. 

• 4 - Main memory is insufficient to perform the Operation. 

• 5 - The handle is in an invalid state for Operation, such as performing an init 
Operation on a handle twice. 

• 6 - Specified key label not found in keyfile. 

• 7 - Certificate not received from partner. 

• 8 - Certificate Validation error. 

• 9 - Error processing cryptography. 

• 10 - Error validating Abstract Syntax Notation (ASN) fields in certificate. 

• 11 - Error connecting to LDAP Server. 

• 12 - Internal unknown error. Report problem to service. 

• 101 - Internal unknown error. Report problem to service. 

• 102 - I/O error reading keyfile. 

• 103 - Keyfile has an invalid internal format. Re-create keyfile. 

• 104 - Keyfile has two entries with the same key. Use iKeyman to remove the 
duplicate key. 

• 105 - Keyfile has two entries with the same label. Use iKeyman to remove the 
duplicate label. 

• 106 - The keyfile password is used as an integrity check. Either the keyfile has 
become corrupted or the password ID is incorrect. 

• 107 - The default key in the keyfile has an expired certificate. Use iKeyman to 
remove certificates that are expired. 

• 108 - There was an error loading one of the GSKdynamic link libraries. Be sure 
GSK was installed correctly. 

• 109 - Indicates that a connection is trying to be made in a gsk environment after 
the GSK_ENVIRONMENT_CLOSE_OPTIONS has been set to 
GSK_DELAYED_ENVIRONMENT_CLOSE and gsk_environment_close() 
function has been called. 

• 201 - Neither the password nor the stash-file name was specified, so the key file 
could not be initialized. 

• 202 - Unable to open the key file. Either the path was specified incorrectly or 
the file permissions did not allow the file to be opened. 

• 203 - Unable to generate a temporary key pair. Report this error to service. 

• 204 - A User Name object was specified that is not found 

• 205 - A Password used for an LDAP query is not correct 

• 206 - An index into the Fail Over list of LDAP Servers was not correct. 


© Copyright IBM Corp. 2002 


171 




• 301 - Indicates that the GSK environment close request was not proper ly 
handled. Cause is most likely due to a gsk_secure_socket*() command being 
attempted after a gsk_close_environment() call. 

• 401 - The System date was set to an invalid value. 

• 402 - Neither SSLv2 nor SSLv3 is enabled. 

• 403 - The required certificate was not received from partner. 

• 404 - The received certificate was formatted incorrectly. 

• 405 - The received certificate type was not supported. 

• 406 - An IO error occurred on a data read or write. 

• 407 - The specified label in the key file could not be found. 

• 408 - The specified key file password is incorrect. The key file could not be 
used. The key file may also be corrupt. 

• 409 - In a restricted cryptography environment, the key size is too long to be 
supported. 

• 410 - An incorrectly formatted SSL message was received from the partner. 

• 411 - The message authentication code (MAC) was not successfully verified. 

• 412 - Unsupported SSL protocol or unsupported certificate type. 

• 413 - The received certificate contained an incorrect signature. 

• 414 - Incorrectly formatted certificate received from partner. 

• 415 - Invalid SSL protocol received from partner. 

• 416 - Internal error. Report problem to service. 

• 417 - The self-signed certificate is not valid. 

• 418 - The read failed. Report this error to service. 

• 419 - The write failed. Report this error to service. 

• 420 - The partner closed the socket before the protocol completed. 

• 421 - The specified V2 cipher is not valid. 

• 422 - The specified V3 cipher is not valid. 

• 423 - Internal error. Report problem to service. 

• 424 - Internal error. Report problem to service. 

• 425 - The handle could not be created. Report this internal error to service. 

• 426 - Initialization failed. Report this internal error to service. 

• 427 - When validating a certificate, unable to access the specified LDAP 
directory. 

• 428 - The specified key did not contain a private key. 

• 429 - A failed attempt was made to load the specified Public-Key Cryptography 
Standards (PKCS) #11 shared library. 

• 430 - The PKCS #11 driver failed to find the token specified by the caller. 

• 431 - A PKCS #11 token is not present in the slot. 

• 432 - The password/pin to access the PKCS #11 token is invalid. 

• 433 - The SSL header received was not a properly SSLV2 formatted header. 

• 501 - The buffer size is negative or zero. 

• 502 - Used with non-blocking I/O. Refer to the non-blocking section for usage. 

• 601 - SSLV3 is required for reset_cipher, and the connection uses SSLV2. 

• 602 - An invalid ID was specified for the gsk_secure_soc_misc function call. 

• 701 - The function call has an invalid ID. This may also be caused by specifying 
an environment handle when a handle for a SSL connection should be used. 
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702 - The attribute has a negative length, which is invalid. 

703 - The enumeration value is invalid for the specified enumeration type. 

704 - Invalid parameter list for replacing the SID cache routines. 

705 - When setting a numeric attribute, the specified value is invalid for the 
specific attribute being set. 

706 - Conflicting parameters have been set for additional certificate validation. 


Appendix A. Possible extended error Codes returned by LDAP SSL function Codes 
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Appendix B. LDAP V3 Schema 

Use the following sections for information about the LDAP V3 Schema. 


Dynamic Schema 

The IBM Tivoli Directory Server Version 5.2 C-Client SDK requires that the Schema 
defined for a Server be stored in the directory's subschemasubentry. 

To access the Schema, you must first determine the subschemasubentry's DN, 
which is obtained by searching the root DSE. To obtain this information from the 
command-line, issue the following command: 

Idapsearch -h hostname -p 389 -b "" -s base "objectclass=*" 

The root DSE information returned from an LDAP V3 Server, such as the IBM 
Directory Server, includes the following: 
subschemasubentry=cn=schema 

where subschemasubentry's DN is "cn=schema". 

Using the subschemasubentry's DN returned by searching the root DSE, Schema 
information can be accessed with the following command-line search: 

Idapsearch -h hostname -p 389 -b "cn=schema" -s base "objectclass=subschema" 

The Schema contains the following information: 

Object dass 

A collection of attributes. A dass can inherit attributes from one or more 
parent classes. 

Attribute typ es 

Contain information about the attribute, such as the name, oid, syntax and 
matching rules. 

IBM attribute types 

The IBM LDAP directory implementation-specific attributes, such as 
database table name, column name, SQL type, and the maximum length of 
each attribute. 

Syntaxes 

Specific LDAP syntaxes available for attribute definitions. 

Matching rules 

Specific matching rules available for attribute definitions. 


Schema queries 

The Idapsearch utility can be used to query the subschema entry. This search can 
be performed by any application using the ldap_search APIs. 

To retrieve all the values of one or more selected attribute types, specify the 
specific attributes desired for the LDAP search. Schema-related attribute types 
include the following: 

• objectclass 
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• objectclasses 

• attributetypes 

• ldapsyntaxes 

• ibmattributetypes 

• matchingrules 


For example, to retrieve all the values for ldapsyntaxes, specify: 
ldapsearch -h host -b "cn=schema" -s base objectclass=* ldapsyntaxes 


which retums something like: 
cn=schema 

ldapsyntaxes=( 1.3.6.1.4.1.1466, 
ldapsyntaxes=( 1.3.6.1.4.1.1466, 
ldapsyntaxes=( 1.3.6.1.4.1.1466, 
Description 1 ) 

ldapsyntaxes=( 1.3.6.1.4.1.1466, 
Description' ) 

ldapsyntaxes=( 1.3.6.1.4.1.1466, 
ldapsyntaxes=( 1.3.6.1.4.1.1466, 
ldapsyntaxes=( 1.3.6.1.4.1.1466, 
ldapsyntaxes=( 1.3.6.1.4.1.1466, 
Description 1 ) 

ldapsyntaxes=( 1.3.6.1.4.1.1466, 
Description 1 ) 

ldapsyntaxes=( 1.3.6.1.4.1.1466, 
Description 1 ) 

ldapsyntaxes=( 1.3.6.1.4.1.1466, 
Description 1 ) 

ldapsyntaxes=( 1.3.6.1.4.1.1466, 
Description 1 ) 

ldapsyntaxes=( 1.3.6.1.4.1.1466, 
ldapsyntaxes=( 1.3.6.1.4.1.1466, 
ldapsyntaxes=( 1.3.6.1.4.1.1466, 
Number 1 ) 

ldapsyntaxes=( 1.3.6.1.4.1.1466, 
ldapsyntaxes=( 1.3.6.1.4.1.1466, 
Description 1 ) 

ldapsyntaxes=( 1.3.6.1.4.1.1466, 
1dapsyntaxes=( IBMAttributeType- 
Type Description' ) 


12 

DESC 

' DN 1 ) 


15 

DESC 

'Directory Stri 

ng' 

16 

DESC 

'DIT Content Rule 

17 

DESC 

'DIT Structure 

Rul e 

24 

DESC 

'Generalized Ti 

me' 

26 

DESC 

1 IA5 String' ) 


27 

DESC 

'INTEGER' ) 


3 1 

DESC ' 

Attribute Type 


30 

DESC 

'Matching Rule 


31 

DESC 

'Matching Rule 

Use 

35 

DESC 

'Name Form 


37 

DESC 

'Object Class 


38 

DESC 

'OID' ) 


5 1 

DESC ' 

Binary' ) 


50 

DESC 

'Telephone 


53 

DESC 

'UTC Time' ) 


54 

DESC 

'LDAP Syntax 



115.121.1.7 DESC 'Boolean' ) 
desc-syntax-oid DESC 'IBM Attribute 


Similarly, to obtain the values for matchingrules, specify: 
ldapsearch -h host -b "cn=schema" -s base objectclass=* matchingrules 


which returns something like: 
cn=schema 

MatchingRules= ( 2.5.13.5 NAME 1 caseExactMatch 1 \ 

SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) 

MatchingRules= ( 2.5.13.2 NAME 1 caselgnoreMatch 1 \ 

SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 

MatchingRules= ( 2.5.13.7 NAME 1 caseExactSubstringsMatch 1 \ 

SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 

Matchi ngRul es= ( 2.5.13.6 NAME 1 caseExactOrderingMatch 1 \ 

SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 

Matchi ngRul es= ( 2.5.13.4 NAME 1 caselgnoreSubstringsMatch 1 \ 

SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 

Matchi ngRul es= ( 2.5.13.3 NAME 'caselgnoreOrderingMatch' \ 

SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 

Matchi ngRul es= ( 1.3.18.0.2.4.405 NAME 1 distinguishedNameOrderingMatch 1 \ 
SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) 

MatchingRules= ( 2.5.13.1 NAME 1 distinguishedNameMatch 1 \ 

SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) 
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MatchingRules= ( 2.5.13.28 NAME 1 generalizedTimeOrderi ngMatch 1 \ 

SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) 

MatchingRules= ( 2.5.13.27 NAME 'generalizedTimeMatch' \ 

SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) 

MatchingRules= ( 1.3.6.1.4.1.1466.109.114.2 NAME 1 caseIgnoreIA5Match 1 \ 
SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) 

MatchingRules= ( 1.3.6.1.4.1.1466.109.114.1 NAME 1 caseExactIA5Match 1 \ 
SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) 

MatchingRules= ( 2.5.13.29 NAME 1 integerFirstComponentMatch' \ 

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) 

MatchingRules= ( 2.5.13.14 NAME 1 integerMatch 1 \ 

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) 

MatchingRules= ( 2.5.13.17 NAME 1 octetStringMatch 1 \ 

SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 ) 

MatchingRules= ( 2.5.13.0 NAME 1 objectldentifierMatch 1 \ 

SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) 

MatchingRules= ( 2.5.13.30 NAME 'objectldentifierFirstComponentMatch' \ 
SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) 

MatchingRules= ( 2.5.13.21 NAME 'telephoneNumberSubstringsMatch' \ 
SYNTAX 1.3.6.1.4.1.1466.115.121.1.50 ) 

MatchingRules= ( 2.5.13.20 NAME 'telephoneNumberMatch' \ 

SYNTAX 1.3.6.1.4.1.1466.115.121.1.50 ) 

MatchingRules= ( 2.5.13.25 NAME 'uTCTimeMatch 1 \ 

SYNTAX 1.3.6.1.4.1.1466.115.121.1.53 ) 


Dynamic Schema changes 

To perform a dynamic Schema change, use LDAP modify with a DN of 
"cn=schema". It is permissible to add, delete or replace only one Schema entity, for 
example, an attribute type or an object dass, at a time. 

To delete a Schema entity, you can simply provide the oid in parentheses: 

( oid ) 

A full description might also be provided. In either case, the matching rule used to 
find the Schema entity to delete is objectldentifierFirstComponentMatch as 
mandated by the LDAP V3 protocol. 

To add or replace a Schema entity, you must provide the LDAP V3 definition and 
you can provide the IBM definition. 

In all cases, you must only provide the definitions of the Schema entity you wish 
to affect. For example, to delete the attribute type cn (its OID is 2.5.4.3), invoke 
ldap_modify() with: 

LDAPMod attr; 

LDAPMod *attrs[] = { &attr, NULL }; 
char *val s [] = { "( 2.5.4.3 )", NULL }; 
attr.mod_op = LDAP_MOD_DELETE; 
attr.mod_type = "attributeTypes"; 
attr.mod_values = vals; 

ldap_modify_s(ldap_session_handle, "cn=schema", attrs); 

To add a new attribute type foo with OID 20.20.20 which is a NAME of length 20 
chars: 

char *valsl[] = { "( 20.20.20 NAME 'foo' SUP NAME )", NULL }; 

char *vals2[] = { "( 20.20.20 LENGTH 20 )", NULL }; 

LDAPMod attrl; 

LDAPMod attr2; 

LDAPMod *attrs[] = { &attrl, &attr2, NULL }; 
attrl.mod_op = LDAP_M0D_ADD; 
attrl.mod_type = "attributeTypes"; 
attrl.mod_values = valsl; 
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attr2.mod_op = LDAP_MOD_ADD; 
attr2.mod_type = "IBMattributeTypes"; 
attr2.mod_values = vals2; 

ldap_modify_s(ldap_session_handle, "cn=schema", attrs); 


To change the object dass top so it allows a MAY attribute type called foo (this 
assumes the attribute type foo has been defined in the Schema): 

LDAPMod attr; 

LDAPMod *attrs[] = { &attr, NULL }; 

attr.mod_op = LDAP_MOD_REPLACE; 

attr.mod_type = "objectClasses"; 

attr.mod_values = "( 2.5.6.0 NAME 'top' ABSTRACT " 

"MUST objectClass MAY foo )"; 
ldap_modify_s(ldap_session_handle, "cn=schema", attrs); 
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Appendix C. LDAP distinguished names 


Distinguished names (DNs) are used to uniquely identify entries in an LDAP or 
X.500 directory. DNs are user-oriented strings, typically used whenever you must 
add, modify or delete an entry in a directory using the LDAP programming 


interface, as w ell as when us ing the LDAP Utilities ldapmodify, ldapsearch 
ldapmodrdn and ldapdelete 


A DN is typically composed of an ordered set of attribute type/attribute value 
pairs. Most DNs are composed of pairs in the following order: 

• common name (cn) 

• Organization (o) or organizational unit (ou) 

• country (c) 


The following string-type attributes represent the set of standardized attribute 
types for accessing an LDAP directory. A DN can be composed of attributes with 
an LDAP syntax of Directory String, including the following: 

• CN - CommonName 

• L - LocalityName 

• ST - StateOrProvinceName 

• O - OrganizationName 

• OU - OrganizationalUnitName 

• C - CountryName 

• STREET - StreetAddress 


Informal definition 

This notation is designed to be convenient for common forms of name. Most DNs 
begin with CommonName (CN), and progress up the naming tree of the directory. 
Typically, as you read from left to right, each component of the name represents 
increasingly larger groupings of entries, ending with CountryName (C). Remember 
that sequence is important. For example, the following two DNs do not identify 
the same entry in the directory: 

CN=wiley coyote, 0=acme, Oanvils, C=US 

CN=wiley coyote, 0=anvils, Oacme, OUS 

Some examples follow. The author of RFC 2253, "UTF-8 String Representation of 
Distinguished Names" is specified as: 

CN=Steve Kille, 0= ISODE Consortium, OGB 

Another name might be: 

CN=Christian Hintema, OINRIA, OFR 

A semicolon ( ; ) can be used as an alternate Separator. The Separators might be 
mixed, but this usage is discouraged. 

CN=Christian Hintema; OINRIA; OFR 
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Here is an example of a multi-valued Relative Distinguished Name, where the 
namespace is flat within an Organization, and department is used to disambiguate 
certain names: 

0U=Sales + CN=J. Smith, 0=Widget Inc., C=US 

The final examples show both methods of entering a comma in an Organization 
name: 

CN=L. Eagle, 0="Sue, Grabbit and Runn", C=GB 
CN=L. Eagle, 0=Sue, Grabbit and Runn, C=GB 


Formal definition 


For a formal, and more complete, d efinition of Distinguished Names that can b e 


used with the LDAP in terfaces, see "RFC 2253, UTF-8 String Representation of 


Distinguished Names" 
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Appendix D. LDAP data interchange format (LDIF) 


This d ocumentation describes t he LDAP Dat a Interchange Format (LDIF), as used 
by the ldapmodify, ldapsearch and ldapadd Utilities. The LDIF specified here is 
also supported by the Server Utilities provided with the IBM Directory 


LDIF is used to represent LDAP entries in text form. The basic form of an LDIF 
entry is: 

dn: <distinguished name> 

<attrtype> : <attrvalue> 

<attrtype> : <attrvalue> 


A line can be continued by starting the next line with a single space or fab 
character, for example: 

dn: cn=John E Doe, o=University of High 
er Learning, c=US 

Multiple attribute values are specified on separate lines, for example: 

cn: John E Doe 
cn: John Doe 

If an <attrvalue> contains a non-US-ASCII character, or begins with a space or a 
colon ( : ), the <attrtype> is followed by a double colon and the value is encoded in 
base-64 notation. For example, the value begins with a space is encoded as: 
cn:: IGJ1Z21ucyB3aXRoIGEgc3BhY2U= 

Multiple entries within the same LDIF file are separated by a blank line. Multiple 
blank lines are considered a logical end-of-file. 


LDIF examples 

LDIF example: Content 

An LDIF content file contains entries that can be loaded to the directory. Here is an 
example of an LDIF content file containing three entries: 

dn: cn=John E Doe, o=University of High 
er Learning, c=US 
cn: John E Doe 
cn: John Doe 
objectclass: person 
sn: Doe 

dn: cn=Bjorn L Doe, o=University of High 
er Learning, c=US 
cn: Björn L Doe 
cn: Björn Doe 
objectclass: person 
sn: Doe 

dn: cn=Jennifer K. Doe, o=University of High 
er Learning, c=US 
cn: Jennifer K. Doe 
cn: Jennifer Doe 
objectclass: person 
sn: Doe 
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jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD 
A4MChA0DQ4SERAT6CgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ 
ERXRTc4UGlRV19iZ2hnPklxeXBkeFxlZ2P/2wBDARESEhgVG 


The jpegPhoto in Jennifer Doe's entry is encoded using base-64. The textual 
attribute values can also be specified in base-64 format. However, if this is the case, 
the base-64 encoding must be in the Code page of the wire format for the protocol, 
that is, for LDAP V2, the IA5 character set and for LDAP V3, the UTF-8 encoding. 

LDIF file: Change types 

An LDIF file that contains change types allows you to modify and delete existing 
directory entries. For example, the following LDIF file entry shows the object dass 
insectopia being added to the existing entry dn= cn=foo, ou=bar using the modify 
change type: 

dn: cn=foo, ou=bar 
changetype: modify 
add: objectclass 
objectclass: insectopia 

For a complete list of of change types, see RFC 2849. 

LDAP Controls 

Change type files can also contain LDAP Controls. LDAP Controls can be used to 
extend certain LDAP Version 3 operations. 

A control must contain a unique object identifier (OID) that identifies the control. 
Make sure your Server Supports the control you want to use. 

The following example shows the LDAP control syntax. Brackets indicate optional 
data; only the OID is required. 

control: <0ID> [true||false] [string || :: <64string >] 

Where: 

• OID is the OID that identifies the control you want to use. 

• string is a string that does not include Line Feed, Carriage Return, NULL, colon, 
space or < symbol. 

• 64string is a base-64 encoded string. 

The following example uses the 1.2.840.113556.1.4.805 control to delete the 
ou=Product Development, dc=airius, dc=com entry: 

dn: ou=Product Development, dc=airius, dc=com 
control: 1.2.840.113556.1.4.805 true 
changetype: delete 

When Controls are included in an LDIF file, implementations might choose to 
ignore some or all of them. This might be necessary if the changes described in the 
LDIF file are being sent on an LDAPv2 connection (LDAPv2 does not support 
Controls), or the particular Controls are not supported by the remote Server. If the 
criticality of a control is "true", then the implementation must either include the 
control, or must not send the Operation to a remote Server. 


See 

"LDAP Controls" on page 58 

and 

Appendix F, "Object Identifiers (OIDs) for 

extended operations and Controls", on page 189 

for more information. 
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Version 1 LDIF support 

The dient Utilities (ldapmodify and ldapadd) have been enhanced to recognize the 
latest version of LDIF, which is identified by the presence of the version: 1 tag at 
the head of the file. Unlike the original version of LDIF, the newer version of LDIF 
supports attribute values represented in UTF-8, instead of the very limited 
US-ASCII. 


Fiowever, manual creation of an LDIF file containing UTF-8 values can be difficult. 
In order to simplify this process, a charset extension to the LDIF format is 
supported. This extension allows an IANA character set name to be specified in the 
header of the LDIF file, along wi th the version number. A limited set of the IANA 


character sets are supported. See "IANA character sets supported by platform" on 


page 184 for the specific charset values that are supported for each operating 
System platform. 


The version 1 LDIF format also supports file URLs. This provides a more flexible 
way to define a file specification. File URLs take the following form: 

attribute:< file:///path 

(where path syntax depends on platform) 


For example, the following are valid file Web addresses: 

jpegphoto:< file:///d: \temp\photos\myphoto.jpg 
(DOS/Windows style paths) 
jpegphoto:< file:///etc/temp/photos/myphoto.jpg 
(Unix style paths) 


Note: The IBM Directory Server Utilities support both the new file URL 
specification as well as the older style, for example, jpegphoto: 

/ etc / temp / myphoto, regardless of the version specification. In other 
the new file URL format can be used without adding the version tag 
LDIF files. 


words, 
to your 


Version 1 LDIF examples 

You can use the optional charset tag so that the Utilities automatically convert from 
the specified character set to UTF-8 as in the following example: 

version: 1 
charset: ISO-8859-1 

dn: cn=Juan Griego, o=University of New Mexico, c=US 
cn: Juan Griego 
sn: Griego 

description:: V2hhdCBhIGNhcmVmdWwgcmVhZGVyIHlvd 
title: Associate Dean 
title: [title in Spanish] 

jpegPhoto:> file:///usr/local/photos/ jgriego.jpg 

In this instance, all values following an attribute name and a single colon are 
translated from the ISO-8859-1 character set to UTF-8. Values following an attribute 
name and a double colon (such as description:: V2hhdCBhIGNhcm... ) must be 
base-64 encoded, and are expected to be either binary or UTF-8 character strings. 
Values read from a file, such as the jpegPhoto attribute specified by the Web 
address in the previous example, are also expected to be either binary or UTF-8. 

No translation from the specified charset to UTF-8 is done on those values. 
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In this example of an LDIF file without the charset tag, content is expected to be in 
UTF-8, or base-64 encoded UTF-8, or base-64 encoded binary data: 

# IBM Directory sample LDIF file 

# 

# The suffix "o=IBM, c=US" should be defined before attempting to load 

# this data. 

version: 1 

dn: o=IBM, c=US 
objectclass: top 
objectclass: Organization 
o: IBM 

dn: ou=Austin, o=IBM, c=US 
ou: Austin 

objectclass: organizationalUnit 

seealso: cn=Linda Carlesberg, ou=Austin, o=IBM, c=US 

This same file can be used without the version: 1 header information, as in 
previous releases of the IBM Directory Server version C-Client SDK: 

# IBM Directory sample LDIF file 

# 

# The suffix "o=IBM, c=US" should be defined before attempting to load 

# this data. 

dn: o=IBM, c=US 
objectclass: top 
objectclass: Organization 
o: IBM 

dn: ou=Austin, o=IBM, c=US 
ou: Austin 

objectclass: organizationalUnit 

seealso: cn=Linda Carlesberg, ou=Austin, o=IBM, c=US 
Note: The textual attribute values can be specified in base-64 format. 


IANA character sets supported by platform 

The following table defines the set of Internet Assigned Numbers Authority 
(IANA)-defined character sets that can be defined for the charset tag in a Version 1 
LDIF file, on a per-platform basis. The value in the left-most column defines the 
text string that can be assigned to the charset tag. An X indicates that conversion 
from the specified charset to UTF-8 is supported for the associated platform, and 
that all string content in the LDIF file is assumed to be represented in the specified 
charset. n/a indicates that the conversion is not supported for the associated 
platform. 


String content is defined to be all attribute values that follow an attribute name 
and a single colon. 


See IANA Character Sets for more information about IANA-registered character 
sets. 


Table 4. lANA-defined character sets by platform 


Character 

Conversion Supported 

Set Name 

Windows 

AIX 

Solaris 

Linux 

HP-UX 

ISO-8859-1 

X 

X 

X 

X 

X 
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Table 4. lANA-defined character sets by platform (continued) 


Character 

Conversion Supported 

Set Name 

Windows 

AIX 

Solaris 

Linux 

HP-UX 

ISO-8859-2 

X 

X 

X 

X 

X 

ISO-8859-5 

X 

X 

X 

X 

X 

ISO-8859-6 

X 

X 

X 

X 

X 

ISO-8859-7 

X 

X 

X 

X 

X 

ISO-8859-8 

X 

X 

X 

X 

X 

ISO-8859-9 

X 

X 

X 

X 

X 

ISO-8859-15 

NA 

X 

X 


X 

IBM437 

X 

NA 

NA 


NA 

IBM850 

X 

X 

NA 


NA 

IBM852 

X 

NA 

NA 


NA 

IBM857 

X 

NA 

NA 


NA 

IBM862 

X 

NA 

NA 


NA 

IBM864 

X 

NA 

NA 


NA 

IBM866 

X 

NA 

NA 


NA 

IBM869 

X 

X 

NA 


NA 

IBM1250 

X 

NA 

NA 


NA 

IBM1251 

X 

NA 

NA 


NA 

IBM1253 

X 

NA 

NA 


NA 

IBM1254 

X 

NA 

NA 


NA 

IBM1255 

X 

NA 

NA 


NA 

IBM1256 

X 

NA 

NA 


NA 

TIS-620 

X 

X 

NA 


NA 

EUC-JP 

NA 

X 

X 

X 

X 

EUC-KR 

NA 

X 

X* 


NA 

EUC-CN 

NA 

X 

X 


NA 

EUC-TW 

NA 

X 

X 


X 

Shift-JIS 

X 

X 

X 

X 

NA 

KSC 

X 

X 

NA 


NA 

GBK 

X 

X 

X* 


NA 

Big5 

X 

X 

X 


X 

GB18030 

X 

X 

X 

X 

NA 

HP15CN 





X (with 
non-GB18030) 


* Supported on Solaris 7 and higher only. 

The new Chinese character set Standard (GB18030) is supported with appropriate 
patches available from www.sun.com and www.microsoft.com: 


Note: On Windows 2000, you must set the environment variable 
zhCNGB18030=TRUE. 
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Appendix E. Deprecated LDAP APIs 


Although the following APIs are still supported, their use is deprecated. Use of the 
newer replacement APIs is strongly encouraged: 


ldap ssl star tQ—use ldap_ssl_client_init() and ldap_ssl_init(). See "LDAP_SSL' 


on page131 


ldap_open()—use ldap_init(). See 

"LDAP INIT" on page 79 


ldap_bind()—use ldap_simple_bind(). See 

"LDAP_BIND / UNBIND" on page 41 

ldap bind s()—use ldap simple bind s(). 

See "LDAP_BIND / UNBIND" on 


page 41 


ldap resu lt2error()—use ldap_parse_result(). See 


page100 


'LDAP PARSE RESULT" on 


ldap_perr or()—use ldap_parse_result(). See |"LDAP_PARSE_RESULT" on 


page100 


ldap get entry Controls np—use ldap get entry Controls. See 


'LDAP_FIRST_ENTRY, LDAP_FIRST_REFERENCE" on page 71 


ldap_parse_reference_np—use ldap_pars e_reference. See "LDAP_FIRST_ENTRY, 


LDAP_FIRST_REFERENCE" on page 71 
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Appendix F. Object Identifiers (OIDs) for extended operations 
and Controls 


The extended Operation and control OIDs in this section are in the root DSE of the 
IBM Tivoli Directory Server 5.2. In this appendix, each OID is defined and its 
svntax specified in the following formats: 

Extended operations: 

Description 

Gives a brief description of the extended Operation. 

Request 

OID and syntax for the extended Operation request. A request generally sets the 
requestValue field. 

Response 

OID and syntax for the extended Operation response. 

Controls: 

Description 

Gives a brief description of the control. 

OID OID for the extended Operation. 

Syntax 

Syntax for the control. 


OIDs for extended operations 

The following table shows OIDs for extended operations. Click on a short name or 
go to the specified page number for more information about an extended 
operation's syntax and usage. 


Table 5. OIDs for extended operations 


Short name 

Description 

OID assigned 

"Attribute type extended 
operations" on page 190 

Retrieve attributes by supported capability: 
operational, language tag, attribute Cache, unique 
or configuration. 

1.3.18.0.2.12.46 

"Begin Transaction" on 

page 191 

Begin a Transactional context. 

1.3.18.0.2.12.5 

"Cascading Control 
Replication" on page 191 

This Operation performs the requested action on 
the Server it is issued to and cascades the call to 
all consumers beneath it in the replication 
topology. 

1.3.18.0.2.12.15 

"Clear Log Request" on 

page 208 

Request to Clear log file. 

1.3.18.0.2.12.20 

"Control Replication" on 
päge"l93| 

This Operation is used to force immediate 
replication, suspend replication, or resume 
replication by a supplier. This Operation is 
allowed only when the dient has update 
authority to the replication agreement 

1.3.18.0.2.12.16 
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Table 5. OIDs for extended operations (continued) 


Short name 

Description 

OID assigned 

"Control Replication Queue" 
on page 194 

This Operation marks items as "already 
replicated" for a specified agreement. This 
Operation is allowed only when the dient has 
update authority to the replication agreement. 

1.3.18.0.2.12.17 

"Control Server Tracing" on 

page195 

Activate or deactivate tracing in the IBM 

Directory Server. 

1.3.18.0.2.12.40 

"DN normalization extended 
Operation" on page 196 

Request to normalize a DN or a sequence of DNs. 

1.3.18.0.2.12.30 

"Dynamic update requests" on 

page 197 

Request to update Server configuration for IBM 
Directory Server. 

1.3.18.0.2.12.28 

"End Transaction" on page 200 

End Transactional context (commit/rollback). 

1.3.18.0.2.12.6 

"Event Resistration Request" 

on page 200 

Request registration for events notification. 

1.3.18.0.2.12.1 

"Event Unregister Request" on 

page 201 

Unregister for events that were registered for 
using an Event Registration Request. 

1.3.18.0.2.12.3 

"Get Lines Request" on 

page 208 

Request to get lines from a log file. 

1.3.18.0.2.12.22 

"Get number of Lines 

Request" on page 208 

Request number of lines in a log file. 

1.3.18.0.2.12.24 

"Kill Connection request" on 

page 202 

Request to kill Connections on the Server. The 
request can be to kill all Connections or kill 
connections by bound DN, IP, or a bound DN 
from a particular IP. 

1.3.18.0.2.12.35 

"Quiesce or Unquiesce 

Server" on page 202 

This Operation puts the subtree into a state where 
it does not accept dient Updates (or terminates 
this state), except for Updates from clients 
authenticated as directory administrators where 
the Server Administration control is present. 

1.3.18.0.2.12.19 

"Start, Stop Server Request" 

on page 203 

Request to Start, stop or restart an LDAP Server. 

1.3.18.0.2.12.26 

"Start TLS" on page 204 

Request to Start Transport Layer Security. 

1.3.6.1.4.1.1466.20037 

"Unique attributes" on 

page 204 

Feature to enforce attribute uniqueness. 

1.3.18.0.2.12.44 

"User Type Request" on 

page 205| 

Request to get the User Type of the bound user. 

1.3.18.0.2.12.37 


Attribute type extended operations 

Description 

Retrieve attributes by supported capability: operational, language tag, 
attribute Cache, unique or configuration. 

Request 

OID 1.3.18.0.2.12.46 
Syntax 

ExtendedRequest ::= SEQUENCE { 

AttributeTypeRequest ENUMERATED { 

OPERATIONAL (0) 
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LANGUAGE TAG (1), 

ATTRIBUTE CACHE (2), 

UNIQUE (3), 

CONFIGURATION (4) 

}. 

hasCharacteristic BOOLEAN } 


Response 

OID 1.3.18.0.2.12.47 
Syntax 

ResponseValue::=SEQUENCE of AttributeNames (orLDAPString) 

The extended Operation response value will retum a list of attribute names 
that match the specified attribute type if the extnended Operation returns 
LDAP_SUCCESS. If the Operation is not successful, no response value 
returns. 

Begin Transaction 

Description 

Begin a Transactional context. 

Request 

OID 1.3.18.0.2.12.5 
Syntax 

On the request, the request value is empty. 

Response 

OID 1.3.18.0.2.12.5 (same as request) 

Syntax 


SEQUENCE { 

} 


transactionID INTEGER 


Cascading Control Replication 

Description 

This Operation performs the requested action on the Server it is issued to 
and cascades the call to all consumers beneath it in the replication 
topology. 

Request 

OID 1.3.18.0.2.12.15 
Syntax 

requestValue ::= SEQUENCE { 
action ActionValue, 
subtreeDN DistinguishedName, 
timeout INTEGER 
} 


ActionValue ::= INTEGER { 
quiesce (0), 
unquiesce (1), 
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replicateNow (2), 
waitForReplication (3) 
} 


The RequestValue field in the extended request contains three fields: 

action 

causes the Server to behave as if it has received the Quiesce Server 
extended Operation. 

replicateNow 

causes the Server to behave as if it had received the Control 
Replication - replicateNow extended Operation. 

waitForReplication 

causes the Server to wait until all pending changes have been 
replicated to its consumers. 

subtreeDN 

identifies the subtree which this Operation affects. There is no value 
signifying to apply this Operation to all subtrees. 

timeout 

Specifies the maximum number of seconds to wait for the 
Operation to complete. 

The Cascading Control Replication Operation performs the requested action 
on the Server it is issued to and cascades the call to all consumers beneath 
it in the replication topology. The Operation returns when one of the 
following conditions occurs: 

1. The request has been completed on all Servers 

2. A failure has occurred at one Server (result indicates the failure and the 
Server) 

3. The timeout value has been exceeded. This Operation is allowed only 
when the dient is authenticated with update authority to all 
agreements in the specified subtree, or is authenticated as a master 
Server for the specified subtree. 

Response 

OID 1.3.18.0.2.12.15 (same as request) 

Syntax 

Response Value SEQUENCE { 

# fields of interest from LDAPResult: 
resultCode INTEGER (0..MAX), 
errorMessage LDAPString, 

# Operation specific failure information: 
supplier LDAPString, 

consumer LDAPString 

} 


This response will be sent for all requests that have a well-formed request 
value. The response value consists of a resultCode with errorMessage and 
information about where the error was detected. The supplier field will 
contain the DNS host name of the Server reporting the error. If the error 
occurs while working with a consumer Server, the consumer field will 
contain the DNS host name of the consumer Server. So the supplier field 
will always be completed, but the consumer field may be empty. 
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The result code will be a Standard LDAP result code. The following return 
codes can be expected from normal Operation either in a LDAPResult or in 
an extended response: 

• LDAP_SUCCESS - Operation was successful 

• LDAP_NO_SUCH_OBJECT - replication context or agreement does not 
exist 

• LDAP_UNWILLING_TO_PERFORM - Object is not a replication context 

• LDAP_INSUFFICIENT_ACCESS - Not authorized to perform Operation. 

• LDAP_TIMEOUT - Operation did not complete within specified time 

Control Replication 

Description 

Used to force immediate replication, suspend replication, or resume 
replication by a supplier. This Operation is allowed only when the dient 
has update authority to the replication agreement 

Request 

OID 1.3.18.0.2.12.16 
Syntax 

requestValue ::= SEQUENCE { 
action ActionValue, 
scope ScopeValue 
entryDN Disti ngui shedName 
} 


ActionValue ::= INTEGER { 
suspend (0), 
resume (1), 
replicateNow (2), 
terminateFullReplication (3) 
} 


ScopeValue ::= INTEGER { 
singleAgreement (0), 
al1 Agreements (1) 

} 


The RequestValue field in the extended request contains three fields: 

Action 

Indicates the action to be performed. 

Scope Indicates whether the request applies to a single agreement, or to 
all agreements within a given subtree. 

entryDN 

For scope=singleAgreement, entryDN names the replication 
agreement the extended Operation is acting on. For 
scope=allAgreements, entryDN names the root entry of the 
replicated subtree for which all agreements are to be acted on. 

Response 

OID 1.3.18.0.2.12.16 (same as request) 

Syntax 
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Response Value ::= SEQUENCE { 

# fields of interest from LDAPResult: 
resultCode INTEGER (0..MAX), 
errorMessage LDAPString, 
consumer LDAPString 
} 


This response will be sent for all requests that have a well-formed request 
value (i.e. Server can successfully decode the request value). The response 
value consists of a resultCode and errorMessage, and host name of the 
associated consumer. The errorMessage may be empty. If a decoding error 
or other internal error (out of memory) occurs, a Standard LDAPResult will 
be returned. 

The result code will be a Standard LDAP result code. The following return 
codes can be expected from "normal" Operation (i.e. a well formed 
extended Operation with valid replication context, agreements, etc.), either 
in a LDAPResult (i.e. NamingException) or in an extended response: 

• Any return code from the underlying Operation being performed 

• LDAP_SUCCESS - Operation was successful 

• LDAP_NO_SUCH_OBJECT - Replication context or agreement does not 
exist 

• LDAP_UNWILLING_TO_PERFORM - Object is not a replication context. 

• LDAP_INSUFFICIENT_ACCESS - Not authorized to perform Operation. 

The consumer component (if not empty) indicates the agreement associated 
with the error (if any) when the scope is allAgreements. It will have the 
hostname & port (ldap.acme.com:389), as that is more likely to mean 
something to the user than the agreement DN. 

Control Replication Queue 

Description 

This Operation marks items as "already replicated" for a specified 
agreement. This Operation is allowed only when the dient has update 
authority to the replication agreement. 

Request 

OID 1.3.18.0.2.12.17 
Syntax 

requestValue ::= SEQUENCE { 
action ActionValue, 
agreementDN DistinguishedName, 
changeld LDAPString 
} 


ActionValue ::= INTEGER { 
skipAll (0), 
skipSingle (1) 

} 


The RequestValue field in the extended request contains three fields: 

Action 

The skipAll action causes the Server to treat all changes that have 
not yet been replicated under the agreement to be skipped (i.e. set 
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the lastChangeld to the newest changeld present in the Change 
table). The skipSingle action causes the specified changeld to be 
skipped. If that changeld is not at the head of the list of pending 
changes, the Operation fails. This ensures that the Operation affects 
only the entry that the administrator believes to be "stuck", and not 
one which the Server has already replicated, or not gotten to yet. 

agreementDN 

Identities the agreement to be controlled. 

changeld 

Identities the change id to be skipped (action = skipSingle). The 
String is the change id value reported as failing in the replication 
agreement status. The changeld is required when the action is 
skipSingle, and ignored otherwise. 

Response 

OID 1.3.18.0.2.12.17 (same as request) 

Syntax 


Response Value SEQUENCE { 

# fields of interest from LDAPResult: 
resultCode INTEGER (0..MAX), 
errorMessage LDAPString, 

# Operation Information: 
changesSki pped INTEGER (0..MAX) 

} 


This response will be sent for a all requests that have a well-formed 
request value (i.e. Server can successfully decode the request value). The 
response value consists of a resultCode with errorMessage and number of 
changes skipped. The errorMessage may be empty. In the case of a skipAll 
request, a request to skipAll when there are no pending changes is 
considered successful, similar to a successful search returning no entries. 

The result code will be a Standard LDAP result code. The following return 
codes can be expected from a well formed extended Operation with valid 
agreement, change id, etc.: 

• LDAP_SUCCESS - Operation was successful 

• LDAP_NO_SUCH_OBJECT -- replication context or agreement does not 
exist 

• LDAP_INSUFFICIENT_ACCESS - dient does not have authority to 
perform this Operation 

• LDAP_UNWILLING_TO_PERFORM - change id is not the next change 
to replicate 

Control Server Tracing 

Description 

Activate or deactivate tracing in the IBM Tivoli Directory Server. 

Request 


OID 1.3.18.0.2.12.40 

Syntax 
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requestValue ::= SEQUENCE { 
action ActionVal iie, 

commandLineOptions LDAPString OPTIONAL 

} 

ActionValue ::= ENUMERATED { 


on 

(1), 

off 

(2), 

chg 

(3), 

cl r 

(4), 

info 

(5) 


} 

Response 

OID 1.3.18.0.2.12.42 

Syntax 

ResponseValue::= { char* output } 

The extended response name field contains the IBM LDTRC Control OID. 
The extended response value field contains an octet string with the output 
from the ldtrc command. 

Possible return codes: 


LDAP Result Value 

Error Condition 

Success 

Issued command to ldtrc 

Insufficient Access 

User is not the Server administrator 

Operations Error 

Bad action value or any other error 


DN normalization extended Operation 

Description 

The Server accepts extended Operation requests to normalize a DN or a list 
of DNs. There are two ways to normalize a DN. The first method is to 
preserve the case of all characters in the DN. The second method is to 
normalize the case of the case insensitive attributes in a DN. 

Request 

OID 1.3.18.0.2.12.30 

Syntax 

RequestValue::= SEQUENCE { 
case INTEGER {preserve(O), normalize (1)}; 

SEQUENCE of DistinguishedName; 

} 

The requestValue field will contain a case value which indicates case 
preserve or case normalize, followed by a list of DNs. The DNs will be 
normalized using the slapi_dn_normalize_v3 and 
slapi_dn_normalize_case_v3 functions. 

Response 

OID 1.3.18.0.2.12.30 
Syntax 
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ResultValue::= SEQUENCE { 

SEQUENCE of SEQUENCE { 

Return Code INTEGER; 

DN Normalized DistinguishedName; 

} 

} 

The Extended Response contains the DN normalize request OID: and one 
of the following return values: 

• Success 

• Operations error 

• Protocol error 

• Other 

The Result value is set if the return value is Success. The value is set as 
follows. Each DN has its own return code. If the return code is not success, 
a null DN is returned. The order of DN values in the response matches the 
order of DN values passed in the request. Possible return codes are: 


LDAP Return Code 

Error Condition 

Success 

The DN was normalized successfully. 

UndefinedAttributeType 

An attribute in the DN is undefined. 

InvalidDNSyntax 

The DN syntax is invalid. 


Dynamic update requests 

Description 

The IBM Tivoli Directory Server Server is able to dynamically update its 
configuration. For the Server to recognize changes to its configuration, a 
request to reread the configuration file must be sent to the ibmslapd Server. 

Request 

OID 1.3.18.0.2.12.28 

Syntax 

RequestValue::= SEQUENCE { 

action INTEGER {rereadFile(G), 

rereadAttribute(l), 
rereadEntry(2), 
rereadSubtree(3)}; 

entry DistinguishedName OPTIONAL; 

attribute DirectoryString OPTIONAL; 

} 


The RequestValue field in the extended request contains three fields: 

Action 

The action is set to one of the following: 

• 0 to reread the entire file. 

If the request is to reread the entire file, the last two fields are 
not needed. 

• 1 to reread a specific attribute. 

If the request is to reread a specific attribute, the last two fields 
are required. 

• 2 to reread the specified entry (OID 1.3.18.0.2.32.15). 
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• 3 to reread the specified subtree (OID 1.3.18.0.2.32.15). 


Entry DN 

The entry DN specifies which entry the attribute is in. 

Attribute 

The attribute specifies which attribute within the entry should be 
updated. 

Only the configuration options that the Server can dynamically 
update are honored in these requests. The attributes that can be 
updated dynamically are: 

cn=Configuration 
ibm-slapdAdminDN 
ibm-slapdAdminPW 
ibm-slapdErrorLog 
ibm-slapdPwEncryption 
ibm-slapdSizeLimit 
ibm-slapdSysLogLevel 
ibm-slapdTimeLimit 
ibm-slapdAdminGroupEnabl ed 
ibm-slapdDerefAliases 

cn=Front End, cn=Configuration 
ibm-slapdACLCache 
ibm-slapdACLCacheSize 
ibm-slapdEntryCacheSize 
ibm-slapdFi1terCacheBypassLimit 
ibm-slapdFi1terCacheSize 
ibm-slapdldleTimeOut 

cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, 
cn=Configuration 
ibm-slapdBulkloadErrors 
ibm-slapdCLIErrors 
ibm-slapdPagedResAl1owNonAdmin 
ibm-slapdPagedResLmt 
ibm-sl apdReadOnly 
ibm-slapdSortKeyLi mit 
ibm-slapdSortSrchAl1owNonAdmi n 
ibm-slapdSuffix 
ibm-slapdLanguageTagsEnabl ed 
ibm-slapdCachedAttributeSize 
ibm-slapdCachedAttributeSize 

cn=Transaction, cn=Configuration 
ibm-slapdMaxNumOfTransactions 
ibm-slapdMaxOpPerTransaction 
ibm-slapdMaxTimeLimitOfTransactions 

cn=Event Notification, cn=Configuration 
ibm-slapdMaxEventsPerConnecti on 
ibm-slapdMaxEventsTotal 

cn=Connection Management, cn=Front End, cn=Configuration 
ibm-slapdAl1owAnon 
ibm-slapdAnonReapingThreshol d 
ibm-slapdBoundReapi ngThreshol d 
ibm-slapdAl1ReapingThreshold 
ibm-slapdldleTimeOut 
ibm-slapdWriteTimeout 
ibm-slapdESizeThreshol d 
ibm-slapdETimeThreshol d 
ibm-slapdEThreadActivate 
ibm-slapdEThreadEnable 
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cn=ConfigDB, cn=Config Backends, cn=IBM Directory, cn=Schemas, 
cn=Configuration 
ibm-slapdReadOnly 

cn=Digest, cn=Configuration 
ibm-slapdDigestAdminUser 
ibm-slapdDigestRealm 
ibm-slapdDigestAttr 

any entry under cn=AdminGroup, cn=Configuration 
ibm-slapdAdminDN 
ibm-slapdAdminPW 

Entry: 

cn=Configuration 

cn=AdminGroup, cn=Configuration (or any entry under it) 
cn=Front End, cn=Configuration 

cn=Connection Management, cn=Front End, cn=Configuration 
cn=Event Notification, cn=Configuration 
cn=Transaction, cn=Configuration 

cn=ConfigDB, cn=Config Backends, cn=IBM Directory, cn=Schemas, 
cn=Configuration 

cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, 
cn=Configuration 
cn=Digest, cn=Configuration 

Subtree: 

cn=Configuration 
cn=Front End, cn=Configuration 
cn=Event Notification, cn=Configuration 
cn=Transaction, cn=Configuration 

cn=ConfigDB, cn=Config Backends, cn=IBM Directory, cn=Schemas, 
cn=Configuration 

cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, 
cn=Configuration 

cn=Connection Management, cn=Front End, cn=Configuration 
cn=AdminGroup, cn=Configuration (or any entry under it) 
cn=Digest, cn=Configuration 

If the Server encounters a problem updating the configuration, the Server 
does not attempt to continue the Updates. In this case, the result is set to 
the error encountered with the last attempted update. If requesting to 
reread the entire file, the Server processes the attributes in the Order in 
which they are listed. 

Response 

OID 1.3.18.0.2.12.29 

Syntax 


The Extended Response will contain the Update Configuration 
Request OID and one of the following result values: 


LDAP Result Value 

Error Condition 

Error Message Value 

Success 

All Updates were successful 

NULL 

UndefinedAttributeType 

An attribute in the 
ibmslapd.conf file is 
undefined 

The attribute 

InvalidAttributeSyntax 

The attribute value is invalid 

The attribute and value 

InvalidDNSyntax 

The DN Syntax is invalid 

The DN 
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LDAP Result Value 

Error Condition 

Error Message Value 

UnwillingToPerform 

The value changed carmot be 
updated dynamically 

The DN of the entry and 
attribute and value that 
cannot be changed 

ObjectClass Violation 

The entry in the 
ibmslapd.conf file violates 
the object dass definition 

The DN of the entry that has 
the object dass violation 

Other 

The Server encountered an 
internal error while 
attempting the update 

More specific Information 
about the error encountered 

NoSuchAttribute* 

The attribute specified in the 
Request Value does not exist 

NULL 

NoSuchObject* 

The object specified in the 
Request Value does not exist 

NULL 


*These LDAP Result values are possible only when the 

RequestValue is set to a specific value. 

Notes: 

1. Updating some configuration attributes will have side effects, 

as follows: 

• Setting the ibm-slapdentrycachesize will reset the 
entry_cache_hit and entry_cache_miss counters. 

• Setting the filter cache size will reset the filter_cache_hit and 
filter_cache_miss counters. 

• Setting any cache size to a size smaller than the current size 
will cause the Server to clean up entries in that cache to meet 
the new maximum cache size requirement. 

2. Entries are removed in least recently used order. 

End Transaction 


Description 

End Transactional context (commit/rollback). 

Request 

OID 1.3.18.0.2.12.6 
Syntax 

SEQUENCE { 

transactionVote ENUMERATED { 
commit (0), 

rollback(l) }, 

transactionID INTEGER 


Response 

OID 1.3.18.0.2.12.6 (same as request) 

Syntax 

On the response, the response value is empty. 


Event Registration Request 

Description 

Request registration for events notification. 
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Request 


OID 1.3.18.0.2.12.1 


Syntax 


changeType ::= ENUMERATED { 
changeAdd (1), 


changeDelete (2), 
changeModify (4), 
changeModDN (8) } 


requestValue = SEQUENCE { 
eventID ENUMERATED { 


LDAP_CHANGE (0)}, 
baseObject LDAPDN, 


scope 

baseObject 
singleLevel 
wholeSubtree 


ENUMERATED { 



type INTEGER OPTIONAL } 


Response 


OID 1.3.18.0.2.12.1 (same as request) 

Syntax 


response ::= OCTET STRING 


The Server returns LDAP_SUCCESS if the registration is successful. The 
response field of the extended response will contain a unique ID 
identifying the client's registration. This registration ID will be an octet 
string of printable characters of the form <hostname.UUID>. 


Event Unregister Request 


Description 

Unregister for events that were registered for using an Event Registration 
Request. 


Request 


OID 1.3.18.0.2.12.3 
Syntax 

requestValue OCTET STRING 

where the requestValue field contains the unique ID returned by 
the Server in the Event Registration Response. 


Response 


OID 1.3.18.0.2.12.3 (same as request) 

Syntax 

If the registration is successfully removed, the LDAPResult field 
contains LDAP_SUCCESS and the response field contains the 
registration ID that was removed. If unsuccessful, 
NO_SUCH_OBJECT is returned. 
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Kill Connection request 


Description 

Request to kill connections on the Server. The request can be to kill all 
connections or kill connections by bound DN, IP, or a bound DN from a 
particular IP. 

Request 

OID 1.3.18.0.2.12.35 


Syntax 

RequestValue: 
SET 0F {type 

SET 0F {type 

} 


= SEQUENCE { 

ReqType 

value Directory String} OPTIONAL 
ReqType 

value Directory String} OPTIONAL 


ReqType ::= ENUMERATED { 
DN (1), 

IP (2) 

} 


For a DN or IP only request only one set of type and value is needed. For 
a DN and IP request both sets of type and value are needed. If there is no 
value it is assumed to kill all connections. 

Response 

OID 1.3.18.0.2.12.36 
Syntax 

ResponseValue::= { int numberKilled 
int numberPending } 

Quiesce or Unquiesce Server 

Description 

This Operation puts the subtree into a state where it does not accept dient 
Updates (or terminates this state), except for Updates from clients 
authenticated as directory administrators where the Server Administration 
control is present. 

Request 

OID 1.3.18.0.2.12.19 

Syntax 

requestValue ::= SEQUENCE { 
quiesce B00LEAN, 
subtreeDn DistinguishedName 
} 


Quiesce: specify TRUE to quiesce the subtree, FALSE to return the subtree 
to normal Operation. SubtreeDn: Specifies the root of the subtree to quiesce. 
The named entry must have the ibm-replicationContext objectclass value. 

Response 

OID 1.3.18.0.2.12.19 (same as request) 

Syntax 
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Response Value ::= SEQUENCE { 

# fields of interest from LDAPResult: 
resultCode INTEGER (0..MAX), 
errorMessage LDAPString, 

} 


This response will be sent for a all requests that have a well-formed 
request value (i.e. Server can successfully decode the request value). The 
response value consists of a resultCode with errorMessage. A new return 
code is defined to handle "already quiesced" rather than overloading 
LDAP_UNWILLING_TO_PERFORM, which is returned for other reasons. 
#define LDAP_REPL_QUIESCE_BAD_STATE 0x101 (shouldn't overlap 
with Standard Server /dient return code) 

The result code will be a Standard LDAP result code or 
LDAP_REPL_QUIESCE_BAD_STATE. The following return codes can be 
expected from a well formed extended Operation with valid agreement, 
change id, etc.: 

• LDAP_SUCCESS - Operation was successful 

• LDAP_NO_SUCH_OBJECT -- replication context or agreement does not 
exist 

• LDAP_INSUFFICIENT_ACCESS - dient does not have authority to 
perform this Operation 

• LDAP_UNWILLING_TO_PERFORM - DN does not name a replication 
context 

• LDAP_REPL_QUIESCE_BAD_STATE - Context is already quiesced (or 
unquiesced) 

Start, Stop Server Request 

Description 

Request to start, stop or restart an LDAP Server. 

Request 

OID 1.3.18.0.2.12.26 

Syntax 

actionType ENUMERATED { 
startServer (1), 
stopServer (2), 
restartServer (3), 

Status (4), 

admindaemonstop (5) 

} 


Set the requestValue field to one of the following actionTypes followed by 
a string containing the command line options for starting or restarting the 
Server. 

The admindaemonstop actionType is new in IBM Tivoli Directory Version 
5.2. It is not available on earlier Servers. 

Response 

OID 1.3.18.0.2.12.27 
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Syntax 

The responseValue field will be an octet string containing any error 
messages. 


Start TLS 

Description 

Request to start Transport Layer Security. 

Request 

OID 1.3.6.1.4.1.1466.20037 

Syntax 

ExtendedRequest [APPLICATION 23] SEQUENCE { 
requestName [0] 1.3.6.1.4.1.1466.20037 

} 

Response 

OID 1.3.6.1.4.1.1466.20037 (same as request) 

Syntax 

ExtendedResponse = [APPLICATION 24] SEQUENCE { 
C0MP0NENTS 0F LDAPResult, 
responseName [10] 1.3.6.1.4.1.1466.20037 

} 


Unique attributes 

Description 

Feature to enforce attribute uniqueness. 

Request 

OID 1.3.18.0.2.12.44 
Syntax 

ExtendedRequest ::= SEQUENCE { 

requestName LDAP0ID // OID for the IBM Unique Attributes 

requestValue LDAP0ID // OID for an attribute requiring uniqueness 

} 

LDAP0ID ::= OCTET STRING 

Response 

OID 1.3.18.0.2.12.45 

Syntax 

ExtendedResponse ::= SEQUENCE { 

C0MP0NENTS 0F LDAPResult, 

responseName LDAP0ID // OID for the IBM Unique Attributes 

Response AttributeValueList // 1ist of all conflicting attribute values 

} 

AttributeValueList ::= SEQUENCE 0F AttributeValue 
AttributeValue OCTET STRING 
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Possible return codes: 


LDAP Result Value 

Error Condition 

Success 

Successful executing of DB2® queries to 
obtain the list of conflicting values 

Insufficient Access 

User is not authorized to access database 
tables 

Operations Error 

Other error 


User Type Request 


Description 

Request to get the User Type of the bound user. 

Request 

OID 1.3.18.0.2.12.37 


Syntax 

RequestVal =: NULL 


Response 

OID 1.3.18.0.2.12.38 


Syntax 


ResponseValiie: := SEQUENCE 
{ 


userType 
numberOfRoles 
roles 
{ 

userRole 


DirectoryString; 

INTEGER; 

SEQUENCE OPTIONAL 

DirectoryString; // 1 numberOfRol es 1 occurrences 


} 


The ResponseValue field in the extended request contains the following 
fields: 

userType 

The userType is used to determine how the password for the 

associated bind DN should be changed. Values include: 

• root_administrator: A user having full IBM Tivoli Directory 
Server administrator privileges. This type of user has 
unrestricted access to all data in the IBM Tivoli Directory Server. 
This included the configuration backend. A root administrator 
can also bind to the Admin Daemon and remotely stop, Start, 
restart, or check the status of the IBM Tivoli Directory Server. 

• admin_group_member: A user belonging to the IBM Tivoli 
Directory Server administrative group. This type of user has 
almost the same access as the root administrator. 

• local_os_user: A user who is bound to the LDAP Server using a 
user name and password defined in the server's local operating 
System user registry. This access is typically provided by a 
specialized backend, for example the OS/400® System projection 
backend or the z/OS"' SDBM backend. This type of user should 
show the operating System backend suffix under "Manage 
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directory". This suffix is identified by the ibm-osregistrycontext 
attribute in the root DSE, and also included in the 
namingcontexts attribute. 

Note: This field is available on OS/400 LDAP Servers only. 

• ldap_user_type: A regulär LDAPuser whose credentials are 
stored in the DIT of the LDAP Server. The user's simple and 
external with SSL bind DN is the DN of an entry in the DIT. The 
user's password is stored in the userpassword attribute of this 
entry. 

• unknown 


userRoles 

Used to determine what capabilities the user has. Values include: 

• server_config_administrator: This user has unrestricted access to 
all Information in the configuration backend and can Start/stop 
the Server. The user can issue dynamic configuration Updates. 

• server_config_group_member: This user can: 

- start and stop the Server. 

- access all configuration information except the administrator 
and admin group credentials. 

- modify own user password. 

- modify all attributes under these entries except the Kerberos 
and Digest-MD5 root administrator bind attributes. 

- Issue dynamic configuration Updates. 

This user cannot: 

- add or remove members from the administrative group. 

- modify own DN, Kerberos ID, or Digest-MD5 ID 

- modify the DN, password, Kerberos ID, or Digest-MD5 ID of 
any administrative group member entry under 
cn=AdminGroup,cn=Configuration. 

- view the password of any other administrative group member 
or the IBM Tivoli Directory Server administrator. 

- add, delete, or modify the audit log setting (the entire 
cn=Audit,cn=Configuration entry) or clear the audit log 

- add or delete the cn=Kerberos,cn=Configuration or 
cn=Digest,cn=Configuration entries, but can to search all 
attributes under these entries. 

- Search or modify the ibm-slapdAdminDN, 
ibm-slapdAdminGroupEnabled or ibm-slapdAdminPW 
attributes under the cn=Configuration entry. 

• server_config_read_only: This user can read, but not modify 
System configuration. This ties into OS/400 access to 
configuration, which allows some users to read the 
configuration, but not update it. This user is bound by the same 
search restrictions listed for the Server Configuration Group 
Member role. In addition, if the user's user type is Root 
Administrator or Administrative Group Member, the member 
can modify the user's own password (ibm-slapdAdminPW 
attribute) stored in the configuration backend. Also, if the user's 
user type is Root Administrator or Administrative Group 
Member, the user can issue a dynamic configuration update on 
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the user's own password (their ibm-slapdAdminPW attribute) 
stored in the configuration backend. 

Note: This field is available on OS/400 LDAP Servers only. 

• directory_administrator: This user has unrestricted access to 
directory data outside the configuration backend (schema, and 
RDBM backends). There are one or two attributes the user can 
search for in the configuration backend (for IDS only). This user 
may not have any authority to the operating specific backends 
(OS/400 System projection backend, z/OS RACF® SDBM). 

• ldap_user_role: This user has almost no access to the 
configuration backend. There are one or two attributes the user 
can search for in the configuration backend (for IDS only). The 
user's access to directory data (schema, and RDBM backends) is 
controlled by ACLs. 

Log access operations 

Three types of extended Operation requests support access to the log files. The IBM 
Tivoli Directory Server administrator supports the following log access extended 
operations: 


"Get number of Lines Request" on page 208 

"Get Lines Request" on page 208 


"Clear Log Request" on page 208 



The Server provides access to the following log files: 

• ibmslapd.log 

• db2cli.log 

• audit.log 

• bulkload.log 

• ibmdiradm.log 

• adminAudit.log (this file is available only if the Admin daemon audit log OID 
(1.3.18.0.2.32.11) is in the list of supported capabilities in the root DSE) 

• ibmslapd.trace.log (this file is available only if the trace log OID (1.3.18.0.2.32.14) 
is in the list of supported capabilities in the root DSE) 

Lines are numbered starting with line 0. A line is considered all characters up to 
and including a new line or 400 characters, whichever comes first. 

To make the log access request, a dient application can use the dient APIs for 
extended operations. An LDAP v3 extended Operation request has the form: 

ExtendedRequest ::= [APPLICATION 23] SEQUENCE { 
requestName [0] LDAP0ID, 

requestValue [1] 0CTET STRING OPTIONAL } 

All the extended requests use a LogType. LogType is defined as: 

LogType ::= ENUMERATED { 

SlapdErrors (1), 

CLIErrors (2), 

AuditLog (4), 

BulkloadLog (8), 

AdminErrors (16), 

AdminAudit (32), 

Debug (64) 

} 
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Get number of Lines Request 

Description 

The get number of lines request retums the number of lines in a given log 
file. 

Request 

OID 1.3.18.0.2.12.24 

Syntax 

RequestValue::= SEQUENCE { 
log LogType 
} 

Set the requestValue field in the extended request to the LogType. 

Response 

OID 1.3.18.0.2.12.25 

Syntax 

The responseValue field will be an octet string containing the 
number of lines in the requested log file. If the Server is unable to 
open the file, the number of lines will be set to -1 and the return 
code set to other or insufficient access. 

Get Lines Request 

Description 

The get lines request returns the requested lines of the requested log file. 

Request 

OID 1.3.18.0.2.12.22 

Syntax 

RequestValue :== SEQUENCE{ 
log LogType; 
firstLine INTEGER; 
lastLine INTEGER; 

} 

Response 

OID 1.3.18.0.2.12.23 
Syntax 

response ::= OCTET STRING 

The responseValue field will be an octet string containing the requested 
lines from the requested log file. Only valid lines will be returned. 

If the Server is unable to open the file, the lines will be set to NULL and 
the return code set to Other or Insufficient access. 

Clear Log Request 

Description 

The clear log request clears the requested log file. 

Request 

OID 1.3.18.0.2.12.20 
Syntax 
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RequestValue::= SEQUENCE { 
log LogType 
} 


Set the requestValue field in the extended request to the LogType. 

Response 

OID 1.3.18.0.2.12.21 

Syntax 

The responseName field in the extended response will be set to the 
number of lines response. If the Server is unable to open the file, 
the return code is set to other or insufficient access. 


OIDs for Controls 

The following table shows OIDs for Controls. Click on the short name or go the 
specified page number for more information about a control's syntax and usage. 


Table 6. OIDs for Controls 


Short name 

Description 

OID assigned 

"Manage DSAIT" 

Causes entries with the "ref" attribute to be 
treated as normal entries, allowing clients to 
read and modify these entries. 

2.16.840.1.113730.3.4.2 

"Paged Search Results" on 

page 210 

Allows management of the amount of data 
returned from a search request. 

1.2.840.113556.1.4.473 

"Password policy" on 

page 210 

Password policy request or response 

1.3.6.1.4.1.42.2.27.8.5.1 

"Proxy authorization" on 

page 210 

Allows a bind entity to assume a proxy 
identity. 

1.3.18.0.2.32.27 

"Replication Supplier Bind 

Control" on page 211 

This control is added by the supplier, if the 
supplier is a gateway Server. 

1.3.18.0.2.10.18 

"Server Administration" on 

page 211 

Allows an update Operation by the 
administrator under conditions when the 
Operation would normally be refused (server 
is quiesced, a read-only replica, etc.) 

1.3.18.0.2.10.15 

"Sorted Search" on page 211 

Allows a dient to receive search results sorted 
by a list of criteria, where each criterion 
represents a sort key. 

1.2.840.113556.1.4.319 

"Transactional Context" on 
page 212 

Marks the Operation as part of a transactional 
context. 

1.3.18.0.2.10.5 

"Tree delete control" on 
page 212 

This control is attached to a Delete request to 
indicate that the specified entry and all 
descendent entries are to be deleted. 

1.2.840.113556.1.4.805 


Manage DSAIT 

Description 

Causes entries with the "ref" attribute to be treated as normal entries, 
allowing clients to read and modify these entries. 

OID 2.16.840.1.113730.3.4.2 

Syntax 

This control has no value. 


Appendix F. Object Identifiers (OIDs) for extended operations and Controls 209 




























































Paged Search Results 

Description 

Allows management of the amount of data returned from a search request. 
OID 1.2.840.113556.1.4.473 

Syntax 

Control :: = SEQUENCE { 
controlType 1.2.840.113556.1.4.473, 
criticality B00LEAN DEFAULT FALSE, 
controlValue OCTET STRING OPTIONAL 
} 

where the OCTET STRING value is the BER encoding of a value with the 

following SEQUENCE: 

realSearchControlValue ::= SEQUENCE { 

Size INTEGER(0..maxint), 

-- requested page size from dient 
-- result set size estimate from Server 
Cookie OCTET STRING } 

Password policy 

Description 

Password policy request or response. 

OID 1.3.6.1.4.1.42.2.27.8.5.1 

Syntax 

PasswordPolicyResponseValue ::= SEQUENCE { 
warning [0] CHOICE OPTIONAL { 

timeBeforeExpiration [0] INTEGER (0 .. maxint), 
graceLoginsRemaining [1] INTEGER (0 .. maxint) } 
error [1] ENUMERATED OPTIONAL { 
passwordExpired (0), 

accountLocked (1), 

changeAfterReset (2), 

passwordModNotAl1owed (3), 
mustSupplyOldPassword (4), 
invalidPasswordSyntax (5), 
passwordTooShort (6), 

passwordTooYoung (7), 

passwordlnHistory (8) } } 

The password policy control has no value on a request. 

Proxy authorization 

Description 

Allows a bind entity to assume a proxy identity. 

OID 1.3.18.0.2.32.27 

Syntax 

Control :: = SEQUENCE { 
controlType LDAP0ID, 
criticality B00LEAN NO DEFAULT, 
controlValue LDAPString 
} 


Where LDAPString contains a proxy DN. 
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The criticality must be set to TRUE in Order to protect clients from 
submitting a request with an unauthorized identity. 

Replication Supplier Bind Control 

Description 

This control is added by the supplier, if the supplier is a gateway Server. 
OID 1.3.18.0.2.10.18 

Syntax 

Control :: = SEQUENCE { 
controlType 1.3.18.0.2.10.18, 
criticality B00LEAN DEFAULT FALSE, 
controlValue OCTET STRING OPTIONAL 
} 

Where OCTET STRING is the Server id of the supplier Server. 

Server Administration 

Description 

Allows an update Operation by the administrator under conditions when 
the Operation would normally be refused (server is quiesced, a read-only 
replica, etc.) 

OID 1.3.18.0.2.10.15 

Syntax 

Control :: = SEQUENCE { 
controlType 1.3.18.0.2.10.15 
} 

The Server Administration control can be specified on an update Operation 
(add, delete, modify, modDn, modRdn) by a dient bound as an directory 
administrator. 

When present, a Server that would normally refuse Updates (quiesced 
Server, forwarder or replica), allows the update. The update is replicated 
like other Updates. The control is used by replication management 
functions to change the replica type on a non-master Server when there is 
no master available (e.g. Failed). The control is used by the compare tool to 
make Updates to a replica that is no longer in sync with the master Server 
(perhaps because of a failed forwarder). 

Because use of this control allows Updates to be made under unusual 
circumstances, it is the responsibility of the dient to ensure that the server 
being updated ends up in a state consistent with other Servers. 

Sorted Search 

Description 

Allows a dient to receive search results sorted by a list of criteria, where 
each criterion represents a sort key. 

OID 1.2.840.113556.1.4.319 

Syntax 


Appendix F. Object Identifiers (OIDs) for extended operations and Controls 211 


SortKeyList :: = SEQUENCE { 

Control Type 1.2.840.113556.1.4.319 
criticality BOOLEAN DEFAULT FALSE, 
Control Value OCTET STRING 
} 


Where the OCTET STRING is the BER encoding of a value with the 
following sequence: 

SortKeyList ::= SEQUENCE of SEQUENCE { 

AttributeType AttributeDescription, 

OrderingRule [0] MatchingRuleld OPTIONAL, 

ReverseOrder [1] BOOLEAN DEFAULT FALSE } 


Transactional Context 


Description 

Marks the Operation as part of a transactional context. 
OID 1.3.18.0.2.10.5 


Syntax 

SEQUENCE { 

} 


transactionID INTEGER 


Tree delete control 

Description 

Request to start Transport Layer Security. 

OID 1.3.6.1.4.1.1466.20037 
Syntax 

This control has no associated data. 

The OID is taken from Microsoft® Active Directory as defined in an 
expired Internet Draft (draft-armijo-ldap-treedelete-02.txt) This control is 
attached to a Delete request to indicate that the specified entry and all 
descendent entries are to be deleted. 

The dient must be bound as a directory administrator or use the master 
DN. This alleviates the need to check authority to delete each of the 
entries. If this is not received during a full replication Operation (as 
indicated by the bind control), the Operation is replicated as a Delete 
request with the same control. 

This control can be used both by full replication and by dient applications. 
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Appendix G. Limited transaction support 


Transactions have four critical properties: 

atomicity 

The transaction must be performed completely. If any part of the 
transaction fails, the entire transaction is rolled back preserving the original 
state of the directory. 

consistency 

The transaction preserves the internal consistency of the database. 

isolation 

The transaction is serialized by a global lock so that it is performed 
independently of any other transactions. 

durability 

The results of a committed transaction are backed up in stable storage, 
usually a disk. 


Usage 

Transactions are limited to a single connection to a single IBM Directory Server and 
are supported by the LDAP extended operations APIs. Only one transaction at a 
time can be running over the same connection. Düring the transaction, no 
nontransactional operations can be issued over the same connection. 

A transaction consists of three parts: 

• An extended request to start the transaction 

• Update operations: 

- add 

- modify 

- modify rdn 

- delete 

Note: The current release does not support some operations, for example, bind, 
unbind, search, extended op, and so forth operations. Referral objects can 
be updated only with manageDsalT control specified. 

• An extended request to end the transaction 

In order to start a transaction, the dient must send an extended request in the form 
of: 

ExtendedRequest ::= [APPLICATION 23] SEQUENCE { 


requestValue [1] OCTET STRING OPTIONAL } 

When the Server receives the request, it generates a unique transaction ID. It then 
sends back an extended response in the form of: 

ExtendedResponse [APPLICATION 24]SEQUENCE{ 

COMPONENTS OF LDAPResult, 


© Copyright IBM Corp. 2002 
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responseName [10] LDAPOID OPTIONAL, 
response [11] OCTET STRING OPTIONAL } 



The dient submits subsequent update operations asynchronously with a control 
attached to all operations. The control contains the transaction ID returned in the 
StartTransaction response. The control has the form of: 

Control SEQUENCE { 

controlType LDAPOID, 

criticality BOOLEAN DEFAULT FALSE, 

controlValue OCTET STRING OPTIONAL } 

The Server does not process update operations immediately. Instead, it saves the 
necessary information of operations in a queue. 

The dient sends an extended request to end the transaction that either commits or 
rolls back the transaction. The request has the same format as the start request. If 
the Server receives the commit Operation result, it uses a global writer lock to 
serialize the transaction. It then retrieves the set of update operations identified by 
the transaction ID from the queue and begins to perform these operations. If all 
operations succeed, the results are committed to the database and the Server sends 
back the success return code. 

As each Operation is performed it generates a success return code unless an error 
occurs during the transaction, in which case an unsuccessful return code is 
returned for all the operations. If any Operation fails, the Server rolls back the 
transaction and sends back the error return code of the failed Operation to the 
Operation in the dient that caused the failure. The EndTransaction Operation also 
receives an unsuccessful return code if the transaction is not successful. For any 
subsequent update operations that still remain in the queue, an unsuccessful return 
code is generated. When the transaction times out, the connection is dropped and 
any subsequent operations receive an unsuccessful return code. 

The Server releases the global lock after the commit or the roll back is performed. 
The event notification and change log operations are performed only if the 
transaction has succeeded. 

Example 

The following example is an ldapmod.c example file, modified for limited 
transaction capability: 

static char sccsid[] = "@(#)17 1.35 11/18/02 progref.idd, Idap, 5.1 15:20:20"; 

/* 

* COMPONENTJIAME: ldap.clients 

* 

* ABSTRACT: generic program to modify or add entries using LDAP with a transaction 

* 

* ORIGINS: 202,27 

* 

* (C) COPYRIGHT International Business Machines Corp. 2002 

* All Rights Reserved 

* Licensed Materials - Property of IBM 

* 

* US Government Users Restricted Rights - Use, duplication or 

* disclosure restricted by GSA ADP Schedule Contract with IBM Corp. 
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*/ 


/* 

* Copyright (c) 1995 Regents of the University of Michigan. 

* All rights reserved. 

* 

* Redistribution and use in source and binary forms are permitted 

* provided that this notice is preserved and that due credit is given 

* to the University of Michigan at Ann Arbor. The name of the University 

* may not be used to endorse or promote products derived from this 

* Software without specific prior written permission. This Software 

* is provided "as is 11 without express or implied warranty. 

*/ 


/* Idaptxmod.c - generic program to modify or add entries using LDAP 
using a single transaction */ 

#include <1dap.h> 

finclude <stdio.h> 

#include <string.h> 

#include <stdlib.h> 
finclude <ctype.h> 
finclude <sys/types.h> 
finclude <sys/stat.h> 

#if !defined( WIN32 ) 
linclude <sys/file.h> 
finclude <fcntl,h> 
linclude <unistd.h> 

#endif 

#define LDAPMODIFY_REPLACE 1 
#define LDAPMODIFY_ADD 2 

#if defined( WIN32 ) 

#define strcasecmp stricmp 
#endif 

#define safe_realloc( ptr, size ) ( ptr == NULL ? malloc( size ) : \ 
realloc( ptr, size )) 

#define MAX_SUPPLIED_PW_LENGTH 256 
#define LDAPMOD_MAXLINE 4096 

/* Strings found in replog/LDIF entries (mostly lifted from slurpd/slurp.h) */ 
#define T_REPLICA_STR "replica" 

#define T_DN_STR "dn" 

#define T_CHANGENUMBER "changenumber" 

#define T_CHANGETYPESTR "changetype" 

#define T_ADDCTSTR "add" 

#define T_MODIFYCTSTR "modify" 

#define T_DELETECTSTR "delete" 

#define T_MODRDNCTSTR "modrdn" 

#define T_M0D0PADDSTR "add" 

#define T_MODOPREPLACESTR "replace" 

#define T_MODOPDELETESTR "delete" 

#define T_MODSEPSTR 
#define T_NEWRDNSTR "newrdn" 

#define T_DELETEOLDRDNSTR "deleteoldrdn" 

extern char * str_getline(char**); 

char * getPassword(void); 

char * read_one_record(FILE *fp); 

#if defined _WIN32 

int getopt (int, char**, char*); 

#endif 
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/* Gl 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 
stati 


obal variables */ 


LDAP *ld 

FILE *fp 

char *prog 
char *binddn 
char *passwd 
char *ldaphost 
char 
char 
char 
char 


= NULL 
= NULL 
= NULL 


NULL; /* LDAP sesssion handle */ 
NULL; /* input file handle */ 


/* program name */ 
/* bind DN */ 

/* bind password */ 


"localhost"; /* Server host name */ 


*mech 
*charset 
*keyfi1e 
*keyfi1e_pw 
*cert_label 
hoplimit = 


char 
int 

int ldapport 
int doit 
int verbose 
int contoper 
int force 
int valsfromfi 
int Operation 
int referrals 
int ldapversion 
int DebugLevel 
int ssl 

int manageDsa 


= NULL 
= NULL 
= NULL 
= NULL 
= NULL 
10 ; 


/* bind mechanism */ 

/* character set for input */ 

/* SSL key database file name*/ 
/* SSL key database password */ 
/* dient certificate label */ 

/* lirrit for referral chasing */ 


LDAP_P0RT; /* Server port number */ 


1 ; 

0 ; 

0 ; 

0 ; 

es = 0; 


/* 0 to make believe */ 

/* 1 for more trace messages */ 
/* 1 to continue after errors */ 


LDAPMODIFY_REPLACE; 

LDAP_0PT_0N; 

LDAP_VERSI0N3; 

0; /* 1 to activate library traces */ 

0; /* 1 to use SSL */ 

LDAP_FALSE; /* LDAP_TRUE to modify referral objects */ 


static LDAPControl manageDsalT = { 
"2.16.840.1.113730.3.4.2", /* 0ID */ 

{ 0, NULL }, /* no value */ 

LDAP_0PT_0N /* critical */ 

}; 


/* NULL terminated array of Server Controls*/ 

static LDAPControl *Server_Controls[3] = {NULL, NULL, NULL}; 

static int Num_0perations = 0; /* count of times one must go to 

ldap_result to check result Codes */ 
static int Message_ID = 0; /* message ID returned by async 

ldap Operation, currently not tracked*/ 
static int abort_flag = 0; /* abort transaction flag set by 

-A parameter */ 

/* Implement getopt() for Windows to parse command line arguments. */ 

#if defined(_WIN32) 
char *optarg = NULL; 
int optind = 1; 

int optopt = 0; 

fdefine EMSG "" 

int getopt(int arge, char **argv, char *ostr) { 
static char *place = EMSG; 
register char *oli; 

if (!*place) { 

if (optind >= arge [| *(place = argv[optind]) != || !*++place) { 

return EOF; 

} 

if (*place == { 

++optind; 
return EOF; 

} 

} 

if ((optopt = (int)*place++) == (int) 1 : 1 || !(oli = strchr(ostr, optopt))) { 
if (!*place) { 

++optind; 

} 
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fprintf(stderr, "%s: %s: %c\n", "getopt", "illegal Option", optopt); 
return ( '?' ); 


if (*++oli != 1 : 1 ) { 
optarg = NULL; 
if (!*place) 

++optind; 

} eise { 
if (*place) { 
optarg = place; 

} eise if (arge <= ++optind) { 
place = EMSG; 

fprintf(stderr, "%s: %s: %c\n", "getopt", "option requires an argument", optopt); 
return 0; 

} eise { 

optarg = argv[optind]; 

} 

place = EMSG; 

++optind; 

} 

return optopt; 

} 

#endif 


/* Display usage Statement and exit. */ 
void usage() 


fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
fprintf(stderr, 
exit(l); 


\nSends modify or add requests to an LDAP Server.\n"); 
usage:\n"); 

%s [options] [-f file]\n", prog); 
where:\n"); 

file: name of input fi1e\n"); 
note:\n"); 

Standard input is used if file is not specified\n"); 
options:\n" ); 

-h host LDAP Server host name\n"); 

-p port LDAP Server port number\n"); 

-D dn bind DN\n"); 

-w password bind password or '?' for non-echoed prompt\n"); 

-Z use a secure ldap connection (SSL)\n"); 

-K keyfile file to use for keys\n"); 

-P key_pw keyfile password\n"); 

-N key_name private key name to use in keyfile\n"); 

-R do not chase referrals\n"); 

-M Manage referral objects as normal entries.\n"); 

-m mechanism perform SASL bind with the given mechanism\n"); 

-0 maxhops maximum number of referrals to follow in a sequence\n"); 

-V version LDAP protocol version (2 or 3; only 3 is supported)\n"); 

-C charset character set name to use, as registered with IANA\n"); 

-a force add Operation as default\n"); 

-r force replace Operation as default\n"); 

-b Support binary values from files (old style paths)\n"); 

-c continuous Operation; do not stop Processing on error\n"); 

-n show what would be done but don't actually do it\n"); 

-v verbose mode\n"); 

-A set transaction abort flag\n"); 

-d level set debug level in LDAP library\n"); 


/* Parse command 1ine arguments. */ 
void parse_arguments(int arge, char **argv) { 
int i = 0; 
int port = 0; 

char *optpattern = "FaAbcRMZnrv?h:V:p:D:w:d:f:K:P:N:C:0:m:"; 
#ifndef _WIN32 
extern char *optarg; 
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extern int optind; 

#endif 

fp = stdin; 

while ((i = getopt(argc, argv, optpattern)) != EOF) { 
switch ( i ) { 
case 'V' : 

ldapversion = atoi (optarg); 
if (ldapversion != LDAP_VERSI0N3) { 
fprintf(stderr, "Unsupported version level supplied.\n"); 
usage(); 

} 

break; 

case 'A 1 : /* force all changes records to be used */ 

abort_flag = 1; 
break; 
case 'a': 

Operation = LDAPMODIFY_ADD; 
break; 

case 1 b 1 : /* read values from files (for binary attributes)*/ 
valsfromfi1 es = 1; 
break; 

case 'c': /* continuous Operation*/ 
contoper = 1; 
break; 

case 1 F 1 : /* force all changes records to be used*/ 
force = 1; 
break; 

case 1 h 1 : /* 1dap host*/ 
ldaphost = strdup( optarg ); 
break; 

case 1 D 1 : /* bind DN */ 
binddn = strdup( optarg ); 
break; 

case 'w'; /* password*/ 
if (optarg && optarg[0] == '?') { 
passwd = getPassword(); 

} eise 

if (!(passwd = strdup( optarg ))) 
perror("password"); 
break; 
case 1 d 1 : 

DebugLevel = atoi(optarg); 
break; 

case 1 f 1 : /* read from file */ 
if ((optarg[0] == '-') && (optarg[l] == '\0')) 
fp = stdin; 

eise if ((fp = fopen( optarg, "r" )) == NULL) { 
perror( optarg ); 
exit( 1 ); 

} 

break; 
case 'p 1 : 

ldapport = atoi ( optarg ); 

port = 1; 

break; 

case 'n 1 : /* print adds, don't actually do them*/ 
doit = 0; 
break; 

case 'r 1 : /* default is to replace rather than add values*/ 
Operation = LDAPMODIFY_REPLACE; 
break; 

case 1 R 1 : /* don't automatically chase referrals*/ 

referrals = LDAP_0PT_0FF; 
break; 

case 1 M 1 : /* manage referral objects as normal entries */ 

manageDsa = LDAP_TRUE; 
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break; 

case '0': /* set maximum referral hop count */ 

hoplimit = atoi ( optarg ); 
break; 

case ’m': /* use SASL bind mechanism */ 

if (!(mech = strdup ( optarg ))) 
perror("mech"); 
break; 

case 'v': /* verbose mode */ 

verbose++; 
break; 
case 'K 1 : 

keyfile = strdup( optarg ); 
break; 
case 1 P 1 : 

keyfi1e_pw = strdup( optarg ); 
break; 
case 1 N ': 

cert_label = strdup( optarg ); 
break; 
case 1 Z ': 
ssl = 1; 
break; 
case 'C': 

charset = strdup(optarg); 
break; 
case : 
default: 
usage(); 

} 

} 


if (arge - optind != 0) 

usage(); 

/* Use default SSL port if none specified*/ 
if (( port == 0 ) && ( ssl )) 
ldapport = LDAPS_P0RT; 

if ( ! DebugLevel ) { 
char *debug_ptr = NULL; 

if ( ( debug_ptr = getenv ( "LDAP_DEBUG" ) ) ) 

DebugLevel = atoi ( debug_ptr ); 

} 

} 

/* Get a password from the user but don't display it. */ 
char* getPassword( void ) { 

char supplied_password[ MAX_SUPPLIED_PW_LENGTH + 1 ]; /* Buffer for password */ 
#ifdef _WIN32 

char in = 1 \0 1 ; /* Input character */ 

int len = 0; /* Length of password */ 

#else 

struct termios echo_control; 
struct termios save_control; 


int fd = 0; /* File descriptor */ 

int attrSet = 0; /* Checked later for reset */ 

/* Get the file descriptor associated with stdin. */ 
fd = fileno( stdin ); 

if (tcgetattr( fd, &echo_control ) != -1) { 
save_control = echo_control; 
echo_control.c_lflag &= ~( ECHO | ECHONL ); 
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if (tcsetattr( fd, TCSANOW, &echo_control ) == -1) { 
fprintf(stderr, "Internal error setting terminal attribute.\n"); 
exit( errno ); 

} 

attrSet = 1; 

} 

lendif 

/* Prompt for a password. */ 

fputs( "Enter password ==> ", stdout ); 

ff1ush( stdout ); 

lifdef _WIN32 

/* Windows 9x/NT will always read from the console, i.e., 
piped or redirected input will be ignored. */ 
while ( in != '\r' && len <= MAX_SUPPLIED_PW_LENGTH ) { 
in = _getch(); 

if (in ! = 1 \r 1 ) { 
supplied_password[len] = in; 
len++; 

} eise { 

suppl ied_password[len] = 1 \0 1 ; 

} 

} 

#el se 

/* Get the password from stdin. */ 

fgets( supplied_password, MAX_SUPPLIED_PW_LENGTH, stdin ); 

/* Remove the newline at the end. */ 

supplied_password[strlen( supplied_password ) - 1] = 1 \0 1 ; 
lendif 

lifndef _WIN32 
/* Reset the terminal. */ 

if (attrSet && tcsetattr( fd, TCSANOW, &save_control ) == -1) { 
fprintf (stderr, "Unable to reset the display An"); 

} 

lendif 

fprintf( stdout, "\n" ); 

return ( supplied_password == NULL )? supplied_password : strdup( supplied_password ); 

} 

/* Rebind callback function. */ 

int rebindproc(LDAP *ld, char **dnp, char **pwp, int *methodp, int freeit) { 
if ( !freeit ) { 

*methodp = LDAP_AUTH_SIMPLE; 
if ( binddn != NULL ) { 

*dnp = strdup( binddn ); 

*pwp = strdup ( passwd ); 

} eise { 

*dnp = NULL; 

*pwp = NULL; 

} 

} eise { 
free ( *dnp ); 
free ( *pwp ); 

} 

return LDAP_SUCCESS; 

} 

/* Connect and bind to Server. */ 
void connect_to_server() { 
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int fai1ureReasonCode, rc, authmethod; 

struct berval ber; 

struct berval *server_creds; 

/* call 1dap_ssl_client_init if V3 and SSL */ 
if (ssl && (ldapversion == LDAP_VERSI0N3)) { 
if ( keyfile == NULL ) { 
keyfile = getenv("SSL_KEYRING"); 
if (keyfile != NULL) { 
keyfile = strdup(keyfile); 

} 

} 


if (verbose) 

printf( "ldap_ssl_client_init( %s, %s, 0, &fai1ureReasonCode )\n", 
((keyfile) ? keyfile : "NULL"), 

((keyfile pw) ? keyfile pw : "NULL")); 

#ifdef LDAP_SSL_MAX 

rc = ibm_set_unrestricted_cipher_support(); 
if (rc != 0) { 

fprintf( stderr, "Warning: ibm_gsk_set_unrestricted_cipher_support failed! 
rc == %d\n", rc ); 

} 

#endif 

rc = ldap_ssl_client_init( keyfile, keyfile_pw, 0, &fai 1 ureReasonCode ); 
if (rc != LDAP_SUCCESS) { 
fprintf( stderr, 

"ldap_ssl_client_init failed! rc == %d, fai1ureReasonCode == %d\n", 
rc, fai1ureReasonCode ); 
exit( 1 ); 

} 

} 


/* Open connection to Server */ 
if (ldapversion == LDAP_VERSI0N3) { 
if (ssl) { 
if (verbose) 

printf("1dap_ssl_init( %s, %d, %s )\n", ldaphost, ldapport, 
((cert_label) ? cert_label : "NULL")); 
ld = 1dap_ssl_init( ldaphost, ldapport, cert_label ); 
if (ld == NULL) { 

fprintf( stderr, "1dap_ss1_init failed\n" ); 
perror( ldaphost ); 
exit( 1 ); 

} 

} eise { 
if (verbose) 

printf("ldap_init(%s, %d) \n", ldaphost, ldapport); 

if ((ld = ldap_init(ldaphost, ldapport)) == NULL) { 
perror(ldaphost); 
exit(l); 

} 

} 

} 


/* Set options */ 

1dap_set_option (ld, LDAP_0PT_PR0T0C0L_VERSI0N, (void * )&ldapversion); 

if (ldapversion == LDAP_VERSI0N3) { 
ldap_set_option (ld, LDAP_0PT_DEBUG, (void * )&DebugLevel); 
ldap_set_option( ld, LDAP_0PT_REFH0PLIMIT, (void *)&hopl imit); 

} 

1dap_set_option (ld, LDAP_OPT_REFERRALS, (void * )referrals); 
if (binddn != NULL) 

ldap_set_rebind_proc( ld, (LDAPRebindProc)rebindproc ); 
if (charset != NULL) { 
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if (1dap_set_iconv_local_charset(charset) != LDAP_SUCCESS) { 
fprintf(stderr, "unsupported charset %s\n", charset); 
exit(0); 

} 

ldap_set_option(ld, LDAP_0PT_UTF8_I0, (void *)LDAP_UTF8_XLATE_0N); 

} 


/* Bind to Server */ 
if (ldapversion == LDAP_VERSI0N3) { 
if ( ! mech ) /* Use simple bind */ { 
rc = ldap_simple_bind_s(ld, binddn, passwd); 
if ( rc != LDAP_SUCCESS ) { 
ldap_perror( ld, "1dap_simple_bind" ); 

/* LDAP_OPT_EXT_ERROR only valuable for ssl communication. 

In this example, for LDAP v3, the bind is the first 
instance in which communication actually flows to the 
Server. So, if there is an ssl configuration error or 
other ssl problem, this will be the first instance where 
it will be detected. */ 
if (ssl) { 

1dap_get_option( ld, LDAP_OPT_EXT_ERROR, &fai1ureReasonCode); 

fprintf( stderr, "Attempted communication over SSL.\n"); 

fprintf( stderr, " The extended error is %d.\n", fai1ureReasonCode); 

} 

exit( rc ); 

} 

} eise /* Presence of mechanism means SASL bind */ { 

/* Special case for mech="EXTERNAL". Unconditionally set bind DN 
and credentials to NULL. This Option should be used in tandem 
with SSL and dient authentication. For other SASL mechanisms, 
use the specified bind DN and credentials. */ 

if (strcmp(mech, LDAP_MECHANISM_EXTERNAL) == 0) { 
rc = ldap_sasl_bind_s (ld, NULL, mech, NULL, NULL, NULL, &server_creds); 
if (rc != LDAP_SUCCESS ) { 
ldap_perror ( ld, "ldap_sasl_bind_s" ); 
exit( rc ); 

} 

} eise { 

if (strcmp(mech, LDAP_MECHANISM_GSSAPI) == 0) { 
rc = 1dap_sasl_bind_s (ld, NULL, mech, NULL, NULL, NULL, &server_creds); 
if (rc ! = LDAPJUCCESS ) { 
ldap_perror ( ld, "ldap_sasl_bind_s" ); 
exit( rc ); 

} 

} eise /* other SASL mechanisms */ { 
ber.bv_len = strlen ( passwd ); 
ber.bv_val = passwd; 

rc = 1dap_sasl_bind_s (ld, binddn, mech, &ber, NULL, NULL, &server_creds); 
if (rc ! = LDAPJUCCESS ) { 
ldap_perror ( ld, "ldap_sasl_bind_s" ); 
exit( rc ); 


} 


} 


} 


/* Read a record from the file. */ 
char * read_one_record(FILE *fp) 

{ 

int len = 0; 

int lcur = 0; 

int lmax = 0; 

char 1ine[LDAPMOD_MAXLINE]; 

char temp[LDAPMOD_MAXLINE]; 

char *buf = NULL; 


222 C-Client SDK Programming Reference 


/* Reads in and changes to ldif form */ 
while (( fgets( line, sizeof(1 ine), fp ) != NULL )) { 
if (!(strncmp(line,"changenumber",10))) 

{do 

fgets(line,sizeof(1 ine),fp); 

while(strncmp(line,"targetdn",8)); /*changes the = to : for parse*/ 

Tine [8] = 

if (!(strncmp(line,"changetype",9))) 

1 i ne [10] = 1 : 1 ; 

if (!(strncmp(line,"changetype:delete",16))) 

(fgets(temp,sizeof(1ine),fp)); /*gets rid of the changetime line after a delete.*/ 
if (!(strncmp(line,"changetime",9))) 

{fgets (1 ine, sizeof (line) ,fp); 
if (! (strncmpO ine, "newrdn" ,6))) 

1 i ne [6] = ' : '; 
el se 

line[7] =':'; 

} 

if (!(strncmp(line,"deleteoldrdn",12))) 

1 ine[12] = 1 : 1 ; 
if ( *line != '\n' ) { 
len = strlen( line ); 
if ( lcur + len + 1 > lmax ) { 
lmax = LDAPMOD_MAXLINE 

*(( lcur + len + 1 ) / LDAPMOD_MAXLINE + 1 ); 
if (( buf = (char *)safe_realloc( buf, lmax )) == NULL ) { 
perror( "safe_real1oc" ); 
exit ( 1 ); 

} 

} 

strcpy( buf + lcur, line ); 
lcur += len; 

} 

eise { 

if ( buf == NULL ) 
continue; /* Ist line keep going */ 
el se 
break; 

} 

} 


return buf; 

} 

/* Read binary data from a file. */ 
int fromfi1e(char *path, struct berval *bv) { 
FILE *fp = NULL; 
long rlen = 0; 
int eof = 0; 

/* "r" changed to "rb", defect 39803. */ 
if (( fp = fopen( path, "rb" )) == NULL ) { 
perror( path ); 
return -1; 

} 


if ( fseek( fp, OL, SEEK_END ) != 0 ) { 
perror( path ); 
fclose( fp ); 
return -1; 

} 


bv->bv_len = ftel1( fp ); 

if (( bv->bv_val = (char *)malloc( bv->bv_len )) == NULL ) { 
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perror( "malloc" ); 
fclose( fp ); 
return -1; 

} 


if ( fseek( fp, 0L, SEEK_SET ) != 0 ) { 
perror( path ); 
fclose( fp ); 
return -1; 

} 


rlen = fread( bv->bv_val, 1, bv->bv_len, fp ); 
eof = feof( fp ); 
fclose( fp ); 

if ( rlen != (bv->bv_len) ) { 
perror( path ); 
return -1; 

} 


return bv->bv_len; 

} 

/* Read binary data from a file specified with a URL. */ 
int fromfi1e_url(char *value, struct berval *bv) { 
char *fi1e = NULL; 
char *src = NULL; 
char *dst = NULL; 


if (strncmp(value, "file:///", 8)) 
return -1; 


/* unescape characters */ 
for (dst = src = &value[8]; (*src ! = 
*dst = *src; 
if (*src++ != '%') 


continue; 
if ((*src >= '0') 
*dst = (*src++ 
eise if ((*src >= 
*dst = (*src++ 
eise if ((*src >= 
*dst = (*src++ 
el se 

return -1; 
if ((*src >= '0') 
*dst += (*src++ 
eise if ((*src >= 
*dst += (*src++ 
eise if ((*src >= 
*dst += (*src++ 
el se 

return -1; 


l& (*src <= '9')) 
'0') « 4; 
a 1 ) && (*src <= 
'a' + 10) « 4; 
A 1 ) && (*src <= 

1 A 1 + 10) « 4; 


l& (*src <= '9')) 
' 0 '); 

a 1 ) && (*src <= 
'a' + 10); 

A 1 ) && (*src <= 

1 A 1 + 10); 


\0'); ++dst) { 


f 1 )) 

F 1 )) 


f')) 

F')) 


*dst = 1 \0 1 ; 


/* On WIN32 platforms the URL must begin with a drive letter. 

On UNIX platforms the initial '/' is kept to indicate absolute 
file path. 

*/ 

lifdef _WIN32 
fi 1 e = value + 8; 

#el se 

fi1e = value + 7; 

#endif 

return fromfi1e(fi1e, bv); 

} 
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/* Add Operation to the modify structure. */ 
void addmodifyop(LDAPMod ***pmodsp, int modop, char *attr, 
char *value, int vlen, int isURL, int isBase64) 

{ 

LDAPMod **pmods = NULL; 
int i = 0; 
int j = 0; 

struct berval *bvp = NULL; 

/* Data can be treated as binary (wire ready) if one of the 
following applies: 

1) it was base64 encoded 

2) charset is not defined 

3) read from an external file 

*/ 

if (isBase64 | 

(charset == NULL) | 
isURL || 

((value != NULL) && valsfromfi1 es && (*value == '/'))) { 
modop |= LDAP_MOD_BVALUES; 

} 

1 = 0 ; 

pmods = *pmodsp; 
if ( pmods != NULL ) { 
for (; pmods[ i ] != NULL; ++i ) { 
if ( strcasecmp( pmods[ i ]->mod_type, attr ) == 0 && 
pmods[ i ]->mod_op == modop ) { 
break; 

} 

} 

} 


if ( pmods == NULL || pmods[ i ] == NULL ) { 

if (( pmods = (LDAPMod * *)safe_realloc( pmods, (i + 2) * 
sizeof( LDAPMod * ))) == NULL ) { 
perror( "safe_real 1oc" ); 
exit( 1 ); 

} 

*pmodsp = pmods; 

pmods[ i + 1 ] = NULL; 

if (( pmods[ i ] = (LDAPMod * )calloc( 1, sizeof( LDAPMod ))) == NULL ) { 
perror( "calloc" ); 
exit( 1 ); 

} 

pmods[ i ]->mod_op = modop; 

if (( pmods[ i ]->mod_type = strdup( attr )) == NULL ) { 
perror( "strdup" ); 
exit( 1 ); 

} 

} 


if ( value != NULL ) { 
if (modop & LDAP_MOD_BVALUES) { 
j = 0; 

if ( pmods[ i ]->mod_bvalues != NULL ) { 
for (; pmods[ i ]->mod_bvalues[ j ] ! = NULL; ++j ) { 

} ’ 

} 

if (( pmods[ i ]->mod_bvalues = 

(struct berval **)safe_realloc( pmods[ i ]->mod_bvalues, 
(j + 2) * sizeof( struct berval *))) == NULL ) { 
perror( "safe_real1oc" ); 
exit( 1 ); 

} 
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pmods[ i ]->mod_bvalues[ j + 1 ] = NULL; 

if (( bvp = (struct berval *)malloc( sizeof( struct berval ))) 
== NULL ) { 
perror( "malloc" ); 
exit( 1 ); 

} 

pmods[ i ]->mod_bvalues[ j ] = bvp; 

/* get value from file */ 
if ( valsfromfi1 es && *value == '/' ) { 
if (fromfile( value, bvp ) < 0 ) 
exit(l); 

} eise if (isURL) { 
if (fromfi1e_url(value, bvp) < 0) 
exit(l); 

} eise { 

bvp->bv_len = vlen; 

if (( bvp->bv_val = (char *)malloc( vlen + 1 )) == NULL ) { 
perror( "malloc" ); 
exit( 1 ); 

} 

memmove( bvp->bv_val, value, vlen ); 
bvp->bv_val[ vlen ] = 1 \0 1 ; 

} 

} eise { 

j = 0; 

if ( pmods[ i ]->mod_values != NULL ) { 
for ( ; pmods[ i ]->mod_values[ j ] != NULL; ++j ) { 

} ’ 

} 

if (( pmods[ i ]->mod_values = 

(char **)safe_realloc( pmods[ i ]->mod_values, 

(j + 2) * sizeof( char *))) == NULL ) { 
perror( "safe_real1oc" ); 
exit( 1 ); 

} 

pmods[ i ]->mod_values[ j + 1 ] = NULL; 

if (( pmods[ i ]->mod_values[ j ] = strdup( value )) == NULL) { 
perror( "strdup" ); 
exit( 1 ); 

} 

} 

} 

} 


/* Delete record */ 
int dodelete( char *dn ) { 
int rc = 0; 

printf( "%sdeleting entry %s\n", (Idoit) ? "!" : dn ); 

if (Idoit) 

return LDAP_SUCCESS; 

rc = 1dap_delete_ext( Id, dn, 

Server_Control s, 

NULL, &Message_ID); 
if ( rc ! = LDAPJUCCESS ) 
ldap_perror( ld, "1dap_delete" ); 
el se 

printf( "delete complete\n" ); 
putchar( 1 \n'); 

/* Increment results to check after end transaction. */ 
Num_0perations++; 
return rc; 
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} 


/* Copy or move an entry. */ 

int domodrdn( char *dn, char *newrdn, int deleteoldrdn ) { 
int rc = 0; 


printf( "%s%s %s to %s\n", ((!doit) ? "!" : 

((deleteoldrdn) ? "moving" : "copying"), dn, newrdn); 
if (Idoit) 

return LDAP_SUCCESS; 

rc = ldap_rename( ld, dn, newrdn, NULL, deleteoldrdn, 

Server_Controls , NULL, 

&Message_ID ); 
if ( rc != LDAP_SUCCESS ) 
ldap_perror( ld, "1dap_rename" ); 
el se 

printf( "rename Operation complete\n" ); 
putchar('\n 1 ); 

/* Increment the count of results to check after end transaction is sent */ 
Num_Operations++; 
return rc; 

} 

/* Print a binary value. If charset is not specified then check to 
see if string is printable anyway. */ 
void print_binary(struct berval *bval) { 
int i = 0; 
int binary = 0; 

printf( "\tBINARY (%ld bytes) ", bval->bv_len); 
if (charset == NULL) { 
binary = 0; 

for (i = 0; (i < (bval->bv_len)) && (Ibinary); ++i) 
if (!isprint(bval->bv_val[i])) 
binary = 1; 
if (Ibinary) 

for (i = 0; (i < (bval->bv_len)); ++i) 
putchar(bval->bv_val[i]); 

} 

putchar('\n 1 ); 

} 

/* Modify or add an entry. */ 

int domodify( char *dn, LDAPMod **pmods, int newentry ) { 
int i, j, op, rc; 
struct berval *bvp; 

if ( pmods == NULL ) { 

fprintf( stderr, "%s: no attributes to change or add (entry %s)\n", 
prog, dn ); 

return LDAP_PARAM_ERROR; 

} 


if ( verbose ) { 

for ( i = 0; pmods[ i ] != NULL; ++i ) { 
op = pmods[ i ]->mod_op & ~LDAP_M0D_BVALUES; 
printf( "%s %s:\n", op == LDAP_M0D_REPLACE ? 
"replace" : op == LDAP_M0D_ADD ? 

"add" : "delete", pmods[ i ]->mod_type ); 
if (pmods[i]->mod_op & LDAP_M0D_BVALUES) { 
if (pmods[ i ]->mod_bvalues != NULL) { 
for (j = 0; pmods[i]->mod_bvalues[j] != NULL; ++j) 
print_binary(pmods[i]->mod_bvalues[j]); 

} 

} eise { 
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if (pmods [i] ->mod_val ues != NULL) { 
for (j = 0; pmods [i] ->mod_values[j] != NULL; ++j) 
printf ("\t%s\n" , pmods [i] ->mod_values[j]); 


} 


} 


if ( newentry ) 

printf( "%sadding new entry %s as a transaction\n", (!doit) ? "!" : dn ) 

el se 

printf( "%smodifying entry %s as a transaction\n", (Idoit) ? "!" : dn ); 

if (!doit) 

return LDAP_SUCCESS; 

if ( newentry ) { 

rc = 1dap_add_ext( ld, dn, pmods, 

Server_Controls, NULL, 

&Message_ID); 

} eise { 

rc = ldap_modify_ext( ld, dn, pmods, 

Server_Controls, NULL, 

&Message_ID ); 

} 

if ( rc ! = LDAPJUCCESS ) { 

ldap_perror( ld, newentry ? "ldap_add" : "1dapjnodify" ); 

} eise if ( verbose ) { 

printf( "%s Operation complete\n", newentry ? "add" : "modify" ); 

} 

putchar( '\n' ); 

/* Increment the count of results to check after end transaction is sent */ 
Num_Operations++; 
return rc; 

} 

/* Process an ldif record. */ 
int process_ldif_rec(char *rbuf) { 
char *1ine = NULL; 

char *dn = NULL; 

char *type = NULL; 

char *value = NULL; 

char *newrdn = NULL; 

char *p = NULL; 

int is_url = 0; 
int is_b64 = 0; 

int rc =0; 

int linenum = 0; 

int vlen = 0; 

int modop = 0; 

int replicaport = 0; 

int expect_modop = 0; 
int expect_sep = 0; 

int expect_ct = 0; 

int expect_newrdn = 0; 

int expect_deleteoldrdn = 0; 
int deleteoldrdn = 1; 

int saw_replica = 0; 

int use_record = force; 
int new_entry = (Operation == LDAPM0DIFY_ADD); 
int delete_entry = 0; 
int got_all = 0; 

LDAPMod **pmods = NULL; 
int version = 0; 
int str_rc = 0; 

while ( rc == 0 && ( line = str_getline( &rbuf )) != NULL ) { 
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++1inenum; 


/* Is thi s a Separator 1 i ne ("-")? */ 

if ( expect_sep && strcasecmp( line, T_MODSEPSTR ) == 0 ) { 

/* If modifier has not been added yet then go ahead and add 
it. The can happen on sequences where there are no 
attribute values, such as: 

DELETE: title 


*/ 

if (value != NULL) 

addmodifyop(&pmods, modop, value, NULL, 0, 0, 0); 
value = NULL; 
expect_sep = 0; 
expect_modop = 1; 
continue; 

} 


str_rc = str_parse_l ine_v_or_bv(1ine, &type, &value, &vlen, 1, &is_url, &is_b64); 
if ((strncmp(type,"changes",7))==0) 

{str_parse_line_v_or_bv(value, &type, &value, &vlen, 1, &is_url, &is_b64);} 
if ((linenum == 1) && (strcmp(type, "version") == 0)) { 
version = atoi (value); 
continue; 

} 


if ((linenum == 2) && (version == 1) && 

(strcmp(type, "charset") == 0)) { 
if (charset != NULL) 
free(charset); 

charset = strdup(value); 

if ((rc = ldap_set_iconv_local_charset(charset)) != LDAP_SUCCESS) { 
fprintf(stderr, "unsupported charset %s\n", charset); 
break; 

} 

1dap_set_option(1d, LDAP_0PT_UTF8_I0, (void *)LDAP_UTF8_XLATE_0N); 
continue; 

} 


if ( dn == NULL ) { 

if ( !use_record && strcasecmp( type, T_REPLICA_STR ) == 0 ) { 
++saw_replica; 

if (( p = strchr( value, )) == NULL ) { 
replicaport = LDAP_P0RT; 

} eise { 

*p++ = 1 \0 1 ; 

replicaport = atoi ( p ); 

} 

if ( strcasecmp( value, ldaphost ) == 0 && 
replicaport == ldapport ) { 
use_record = 1; 

} 

} eise if ( strcasecmp( type, T_DN_STR ) == 0 ) { 
if (( dn = strdup( value )) == NULL ) { 
perror( "strdup" ); 
exit ( 1 ); 

} 

expect_ct = 1; 

} 

continue; /* skip all lines until we see "dn:" */ 

} 


if ( expect_ct ) { 
expect_ct = 0; 

if ( !use_record && saw_replica ) { 

printf( "%s: skipping change record for entry: %s\n\t(LDAP host/port does 
not match replica: lines)\n", prog, dn ); 
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free( dn ); 
return 0; 


} 

/* this is an 1 dif-change-record */ 
if ( strcasecmp( type, T_CHANGETYPESTR ) == 0 ) { 
if ( strcasecmp( value, T_MODIFYCTSTR ) == 0 ) { 
new_entry = 0; 
expect_modop = 1; 

} eise if ( strcasecmp( value, T_ADDCTSTR ) == 0 ) { 
modop = LDAP_M0D_ADD; 
new_entry = 1; 

} eise if ( strcasecmp( value, T_M0DRDNCTSTR ) == 0 ) { 
expect_newrdn = 1; 

} eise if ( strcasecmp( value, T_DELETECTSTR ) == 0 ) { 
got_all = delete_entry = 1; 

} eise { 

fprintf( stderr, 

"%s: unknown %s \"%s\" (1 ine %d of entry: %s)\n", 
prog, T_CHANGETYPESTR, value, linenum, dn ); 
rc = LDAP_PARAM_ERROR; 

} 

continue; 

/* this is an 1 dif-attrval-record */ 

} eise { 

if (Operation == LDAPMODIFY_ADD) { 
new_entry = 1; 
modop = LDAP_M0D_ADD; 

} eise 

modop = LDAP_MOD_REPLACE; 

} 

} 

if (expect_modop) { 
expect_modop = 0; 
expect_sep = 1; 

if ( strcasecmp( type, T_M0D0PADDSTR ) == 0 ) { 
modop = LDAP_M0D_ADD; 
continue; 

} eise if ( strcasecmp( type, T_M0D0PREPLACESTR ) == 0 ) { 
modop = LDAP_MOD_REPLACE; 
continue; 

} eise if ( strcasecmp( type, TJWOPDELETESTR ) == 0 ) { 
modop = LDAP_MOD_DELETE; 
continue; 

} eise { 
fprintf(stderr, 

"%s: unknown mod_spec \"%s\" (1 ine %d of entry: %s)\n", 
prog, type, linenum, dn); 
rc = LDAP_PARAM_ERROR; 
continue; 

} 

} 

if ( expect_newrdn ) { 

if ( strcasecmp( type, T_NEWRDNSTR )==©){ 
if (( newrdn = strdup( value )) == NULL ) { 
perror( "strdup" ); 
exit( 1 ); 

} 

expect_deleteoldrdn = 1; 
expect_newrdn = 0; 

} eise { 

fprintf( stderr, "%s: expecting \"%s:\" but saw \"%s:\" (1 ine %d of entry %s)\n" 
prog, T_NEWRDNSTR, type, linenum, dn ); 
rc = LDAP_PARAM_ERROR; 
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} 

} eise if ( expect_deleteoldrdn ) { 
if ( strcasecmp( type, T_DELETEOLDRDNSTR ) == 0 ) { 
deleteoldrdn = ( *value == '0' ) ? 0 : 1; 
got all = 1; 

} eise { 

fprintf( stderr, "%s: expecting \"%s:\" but saw \"%s:\" (1 ine %d of entry %s)\n", 
prog, T_DELETEOLDRDNSTR, type, linenum, dn ); 
rc = LDAP_PARAM_ERROR; 

} 

} eise if ( got_all ) { 

fprintf( stderr, "%s: extra lines at end (1 ine %d of entry %s)\n", 
prog, linenum, dn ); 
rc = LDAP_PARAM_ERROR; 

} eise { 

addmodifyop(&pmods, modop, type, value, vlen, is_url, is_b64); 
type = NULL; 
value = NULL; 

} 


/* If last Separator is missing go ahead and handle it anyway, even 
though it is technically invalid ldif format. */ 
if (expect_sep && (value != NULL)) 
addmodifyop(&pmods, modop, value, NULL, 0, 0, 0); 


if ( rc == 0 ) { 
if (delete_entry) 
rc = dodelete( dn ); 

eise if (newrdn != NULL) 

rc = domodrdn( dn, newrdn, deleteoldrdn ); 
eise if (dn != NULL) 

rc = domodify( dn, pmods, new_entry ); 


if (dn != NULL) 
free( dn ); 
if ( newrdn != NULL ) 
free( newrdn ); 
if ( pmods != NULL ) 
ldap_mods_free( pmods, 1 ); 

return rc; 

} 

/* Process a mod record. */ 
int process_ldapmod_rec( char *rbuf ) { 
char *1ine = NULL; 

char *dn = NULL; 

char *p = NULL; 

char *q = NULL; 

char *attr = NULL; 

char *value = NULL; 

int rc =0; 

int linenum = 0; 

int modop = 0; 

LDAPMod **pmods = NULL; 

while ( rc == 0 && rbuf != NULL && *rbuf != 1 \0 1 ) { 

++1inenum; 

if (( p = strchr( rbuf, '\n' )) == NULL ) { 
rbuf = NULL; 

} eise { 

if ( *(p - 1) == '\V ) { /* lines ending in 1 \ 1 are continued */ 
strcpy( p - 1, p ); 
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rbuf = p; 
continue; 

} 

*p++ = 1 \0'; 

rbuf = p; 

} 

if ( dn == NULL ) { /* first line contains DN */ 
if (( dn = strdup( line )) == NULL ) { 
perror( "strdup" ); 
exit( 1 ); 

} 

} eise { 

if (( p = strchr( line, '=' )) == NULL ) { 
value = NULL; 

p = 1 ine + strlen( line ); 

} eise { 

*p++ = 1 \0 1 ; 

value = p; 

} 


for ( attr = line; *attr != 1 \0 1 && isspace( *attr ); ++attr 
/* skip attribute leading white space */ 


*q = 


for ( q = p - 1; q > attr && isspace( *q ); --q ) { 
1 \0'; /* remove attribute trailing white space */ 

} 


if ( value != NULL ) { 
while ( isspace( *value )) { 

++value; /* skip value leading white space */ 

} 

for ( q = value + strlen( value ) - 1; q > value && 
isspace( *q ); —q ) { 

*q = '\0'; /* remove value trailing white space */ 

} 

if ( *value == 1 \0' ) { 
value = NULL; 

} 

} 


if ((value == NULL) && (Operation == LDAPMODIFY_ADD)) { 
fprintf( stderr, "%s: missing value on line %d (attr is %s)\n", 
prog, 1inenum, attr ); 
rc = LDAP_PARAM_ERROR; 

} eise { 

switch ( *attr ) { 
case 

modop = LDAP_MOD_DELETE; 

++attr; 

break; 

case 

modop = LDAP_MOD_ADD; 

++attr; 
break; 
default: 

modop = (Operation == LDAPMODIFY_REPLACE) 

? LDAP_MOD_REPLACE : LDAP_MOD_ADD; 
break; 

} 


addmodifyop( &pmods, modop, attr, value, 

( value == NULL ) ? 0 : strlen( value ), 0, 0); 


} 

line = rbuf; 
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i f ( rc == 0 ) { 
if ( dn == NULL ) 
rc = LDAP_PARAM_ERROR; 
el se 

rc = domodify(dn, pmods, (Operation == LDAPMODIFY_ADD)); 


if ( pmods != NULL ) 
ldap_mods_free( pmods, 1 ); 
if ( dn != NULL ) 
free( dn ); 


return rc; 

} 

main( int arge, char **argv ) { 
char *rbuf = NULL; 
char *start = NULL; 
char *p = NULL; 
char *q = NULL; 
char *tmpstr = NULL; 
int rc = 0; 
int i = 0; 
int use_ldif = 0; 

int num_checked = 0; 

char *Start_Transaction_OID 
char *End_Transaction_OID 
char *Control_Transaction_OID 
char *Returned_OID 
struct berval *Returned_BerVal 
struct berval Request_BerVal 
char *Berval 
LDAPMessage *LDAP_result 


= LDAP_START_TRANSACTION_OID; 

= LDAP_END_TRANSACTION_OID; 

= LDAP_TRANSACTION_CONTROL_OID; 
= NULL; 

= NULL; 

= ( 0 , 0 ); 

= NULL; 

= NULL; 


/* Strip off any path info on program name */ 
#if defined( _WIN32 ) 

if ((prog = strrchr(argv[0], '\\')) != NULL) 
++prog; 
el se 

prog = argv [0]; 

#el se 

if (prog = strrchr(argv[0], '/')) 

++prog; 
el se 

prog = argv [0]; 

#endif 


#if defined( _WIN32 ) 

/* Convert string to lowercase */ 
for (i = 0; prog[i] != 1 \0 1 ; ++i) 
prog [i ] = tolower(prog[i]); 

/* Strip ending .exe from program name */ 
if ((tmpstr = strstr(prog, ".exe")) != NULL) 
*tmpstr = 1 \0 1 ; 

#endif 

if ( strcmp( prog, "ldaptxadd" ) == 0 ) 
Operation = LDAPM0DIFY_ADD; 

/* Parse command line arguments. */ 
parse_arguments(arge, argv); 

/* Connect to Server. */ 
if (doit) 

connect_to_server(); 
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/* Disable translation if reading from file (they must specify the 
translation in the file). */ 
if (fp != stdin) 

ldap_set_option(ld, LDAP_0PT_UTF8_I0, (void *)LDAP_UTF8_XLATE_0FF); 

/* Do the StartTransaction extended Operation. 

The transaction ID returned must be put into the Server control 
sent with all update operations. */ 
rc = ldap_extended_operation_s ( ld, Start_Transaction_OID, 
&Request_BerVal, NULL, NULL, 

&Returned_OID, 

&Returned_BerVal); 
if (verbose) { 

printf("ldap_extended_operation(start transaction) RC=%d\n", rc); 


if ( rc ! = LDAPJUCCESS) { 
fprintf(stderr, "Start transaction rc=%d -> %s\n", 
rc, ldap_err2string(rc)); 
exit( rc ); 

} 


/* Allocate the Server control for transactions. */ 
if (( Server_Controls[0] = 

(LDAPControl *)malloc( sizeof( LDAPControl ))) == NULL ) { 
perror("mal1oc"); 
exit( 1 ); 

} 

/* Allocate the Server control's berval. */ 
if ((Server_Controls[0]->ldctl_value.bv_val = 

(char *) calloc (1, Returned_BerVal ->bv_len + 1)) == NULL) { 
perror("cal1oc"); 
exit(l); 

} 


/* Copy the returned berval length and value into the Server control */ 
Server_Controls[0]->ldctl_value.bv_len = Returned_BerVal-> bv_len; 
memcpy(Server_Controls[0]->1 dctl _val ue.bv_val, 

Returned_BerVal->bv_val , Returned_BerVal->bv_l en); 

/* Set the control type to Transaction_Control_OID */ 

Server_Controls[0]->1dctl_oid = Control_Transaction_OID; 

/* Set the criticality in the control to TRUE */ 

Server_Controls[0]->1dctl_iscritical = LDAP_0PT_0N; 

/* If referral objects are to be modified directly, */ 
if (manageDsa == LDAP_TRUE) { 

/* then set that Server control as well. */ 

Server_Controls[1] = &manageDsaIT 

} 


/* Initialize the count of operations that will be in the transaction. 

This count will be incremented by each Operation that is performed. 

The count will be the number of calls that must be made to ldap_result 
to get the results for the operations. 

*/ 

Num_0perations = 0; 

/* Do operations */ 
rc = 0; 

while ((rc == 0 || contoper) && (rbuf = read_one_record( fp )) != NULL ) { 
/* We assume record is ldif/slapd.replog if the first line 
has a colon that appears to the left of any equal signs, 0R 
if the first line consists entirely of digits (an entry id). */ 
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use_ldif=l; 

Start = rbuf; 

if ( use_ldif ) 

rc = process_ldif_rec( Start ); 
eise 

rc = process_ldapmod_rec( Start ); 
free( rbuf ); 

} 


/* Finish the transaction, committing or rolling back based on input parameter. */ 
rc = 0; 

Request_BerVal.bv_len = Returned_BerVal->bv_len + 1; 
if ((Berval = 

( char *) malloc (Returned_BerVal->bv_len + 1)) == NULL) { 
perror("malloc"); 
exit(l); 

} 


memcpy (&Berval [1], Returned_BerVal->bv_val, Returned_BerVal->bv_len); 
Berval [0] = abort_flag ? 1 \ 1 1 : 1 \0 1 ; 

Request_BerVal.bv_val = Berval; 

rc = ldap_extended_operation_s ( ld, 

End_Transaction_OID, 

&Request_BerVal, NULL, NULL, 

&Returned_OID, 

&Returned_BerVal); 
if (verbose) { 

printf("1dap_extended_operation(end transaction) RC=%d\n", rc); 


if ( rc != LDAP_SUCCESS) { 
fprintf(stderr, "End transaction rc=%d -> %s\n", 
rc, ldap_err2string(rc)); 
exit( rc ); 

} 


/* Process the results of the operations in the transaction. 

At this time we will not be concerned about the correctness 
of the message numbers, just whether the operations succceeded or not. 
We could keep track of the Operation types and make sure they are all 
accounted for. */ 

for ( num_checked = 0; num_checked < Num_Operations; num_checked++ ) { 
if (verbose) { 

printf("processing %d of %d Operation results\n", 

1 + num_checked, Num_Operations); 

} 


rc = ldap_result (ld , LDAP_RES_ANY, LDAP_MSG_ONE, NULL, &LDAP_result); 
if ( rc <= 0) { 
if (rc == 0) 

fprintf(stderr, "Operation %d timed out\n", num_checked); 
if (rc < 0 ) 

fprintf(stderr, "Operation %d failed\n", num_checked); 
exit( 1 ); 

} 

} 


/* Unbind and exit */ 
if (doit) 

1 dap_unbi nd (1 d); 

exit(0); 
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The following is an example makefile: 


# C0MP0NENT_NAME: examples 

# 

# ABSTRACT: makefile to generate LDAP dient programs for transactions 

# 

# ORIGINS: 202,27 

# 

# (C) COPYRIGHT International Business Machines Corp. 2002 

# All Rights Reserved 

# Licensed Materials - Property of IBM 

# 

# US Government Users Restricted Rights - Use, duplication or 

# disclosure restricted by GSA ADP Schedule Contract with IBM Corp. 

# 


# Default definitions 

############################################################################# 

CC = cl.exe 
LD = link.exe 
RM = erase /f 
HARDLN = copy 

### Note: Your install path may be different 
LDAPHome = D:/Program Fi 1es/IBM/LDAP 


############################################################################# 

# General Compiler options 

############################################################################# 


DEFINES = /DNDEBUG /DWIN32 /D_C0NS0LE /D_MBCS /DNT /DNEEDPROTOS 
INCLUDES= /I"$(LDAPHome)/include" 

CFLAGS = /nologo /MD /GX /Z7 $(INCLUDES) $ (DEFINES) 


############################################################################# 


# General linker options 

############################################################################# 


LIBS = kernel32.1ib user32.1ib gdi32.1ib winspool.lib comdlg32.1ib\ 
advapi32.1ib Shell32.1ib ole32.1ib oleaut32.1ib uuid.lib odbc32.1ib\ 
odbccp32.1ib wsock32.1ib 

# Use the following definition to link the sample programs statically. 
#CLIENT_LIBS = 1dapstatic.1ib libldif.lib setloci.lib iconvi.lib 

# Use the following definition to link the sample programs with 

# the LDAP shared library. 

CLIENT_LIBS = ldap.lib libldif.lib setloci.lib 
LDIR = /LIBPATH:"$(LDAPHome)"/I ib 

LFLAGS = /nologo /subsystem:console /incremental:no \ 

$(LDIR) $(LIBS) $(CLIENT_LIBS) 


############################################################################# 


# Targets 

############################################################################# 


all: ldaptxmod.exe ldaptxadd.exe 

ldaptxmod.exe: ldaptxmod.obj 
$(LD) $ (LFLAGS) /out:$@ $** 

ldaptxadd.exe: ldaptxmod.exe 
$(RM) $0 

$(HARDLN) ldaptxmod.exe ldaptxadd.exe 
.c.obj:: 

$(CC) $(CFLAGS) /c $< 
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ldaptxmod.obj: ldaptxmod.c 
clean: 

$(RM) ldaptxmod.exe ldaptxadd.exe ldaptxmod.obj 
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Appendix H. Notices 


This information was developed for products and Services offered in the U.S.A. 
IBM might not öfter the products, Services, or features discussed in this document 
in other countries. Consult your local IBM representative for information on the 
products and Services currently available in your area. Any reference to an IBM 
product, program, or Service is not intended to state or imply that only that IBM 
product, program, or Service may be used. Any functionally equivalent product, 
program, or Service that does not infringe any IBM intellectual property right may 
be used instead. However, it is the user's responsibility to evaluate and verify the 
Operation of any non-IBM product, program, or Service. 

IBM may have patents or pending patent applications covering subject matter in 
this document. The furnishing of this document does not give you any license to 
these patents. You can send license inquiries, in writing, to: 

IBM Director of Licensing 
IBM Corporation 
North Castle Drive 
Armonk, NY 10504-1785 
U.S.A. 

For license inquiries regarding double-byte (DBCS) information, contact the IBM 
Intellectual Property Department in your country or send inquiries, in writing, to: 

IBM World Trade Asia Corporation Licensing 
2-31 Roppongi 3-chome, Minato-ku 
Tokyo 106, Japan 

The following paragraph does not apply to the United Kingdom or any other 
country where such provisions are inconsistent with local law: 

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS 
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER 
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS 
FOR A PARTICULAR PURPOSE. Some States do not allow disclaimer of express or 
implied warranties in certain transactions, therefore, this Statement may not apply 
to you. 

This information could include technical inaccuracies or typographical errors. 
Changes are periodically made to the information herein; these changes will be 
incorporated in new editions of the information. IBM may make improvements 
and/or changes in the product(s) and/or the program(s) described in this 
information at any time without notice. 

Any references in this information to non-IBM Web sites are provided for 
convenience only and do not in any mariner serve as an endorsement of those Web 
sites. The materials at those Web sites are not part of the materials for this IBM 
product and use of those Web sites is at your own risk. 

IBM may use or distribute any of the information you supply in any way it 
believes appropriate without incurring any Obligation to you. 
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Licensees of this program who wish to have information about it for the purpose 
of enabling: (i) the exchange of information between independently created 
programs and other programs (including this one) and (ii) the mutual use of the 
information which has been exchanged, should contact: 

IBM Corporation 

Department LZKS 

11400 Burnet Road 

Austin, TX 78758 

U.S.A. 

Such information may be available, subject to appropriate terms and conditions, 
including in some cases, payment of a fee. 

The licensed program described in this document and all licensed material 
available for it are provided by IBM under terms of the IBM Customer Agreement, 
IBM International Program License Agreement, or any equivalent agreement 
between us. 

Any performance data contained herein was determined in a controlled 
environment. Therefore, the results obtained in other operating environments may 
vary significantly. Some measurements may have been made on development-level 
Systems and there is no guarantee that these measurements will be the same on 
generally available Systems. Furthermore, some measurement may have been 
estimated through extrapolation. Actual results may vary. Users of this document 
should verify the applicable data for their specific environment. 

Information conceming non-IBM products was obtained from the suppliers of 
those products, their published announcements or other publicly available sources. 
IBM has not tested those products and cannot confirm the accuracy of 
performance, compatibility or any other claims related to non-IBM products. 
Questions on the capabilities of non-IBM products should be addressed to the 
suppliers of those products. 

All statements regarding IBM's future direction or intent are subject to change or 
withdrawal without notice, and represent goals and objectives only. 

All IBM prices shown are IBM's suggested retail prices, are current and are subject 
to change without notice. Dealer prices may vary. 

Trademarks 

The following terms are trademarks of International Business Machines 

Corporation in the United States, or other countries, or both: 

AIX, 

IBM 

World Registry 

Microsoft, Windows, and Windows NT are registered trademarks of Microsoft 
Corporation. 

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the 
United States, other countries, or both. 

UNIX is a registered trademark of The Open Group. 
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Other Company, product, and Service names may be trademarks or Service marks 
of others. 
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